code-crispies/specs/004-pedagogical-messages/plan.md

Implementation Plan

1. Objective

Rewrite all answer-revealing validation error messages across lesson JSON files to use pedagogical hints (concept questions, property-name nudges, directional guidance) instead of literal CSS solutions. This eliminates the fail-then-copy anti-pattern and promotes genuine learning.

2. Approach

Phase-based, content-first strategy:

1. Define a message style guide with 3 hint categories:

   • Concept question: "Which property adds space inside an element?" (for property discovery)
   • Property hint: "Check the padding property" (when the property is known but value is wrong)
   • Directional nudge: "The items need to wrap to the next line" (for layout concepts)

2. Rewrite English priority modules first (flexbox, box-model, colors, positioning) — these are 100% answer-revealing and form the template for all other rewrites.

3. Rewrite remaining English modules, reusing the same hint patterns established in step 2.

4. Update localized variants with equivalent pedagogical messages in each target language (ar, de, es, pl, uk), translating the English hints while preserving natural phrasing in each language.

5. Run npm run format.lessons to ensure consistent formatting, then run tests.

3. File Mapping

Files to modify (message field only, no validation logic changes):

English priority (create → N/A, modify → 4, delete → N/A):

• lessons/flexbox.json — modify 6 messages
• lessons/01-box-model.json — modify 10 messages
• lessons/03-colors.json — modify 4 messages
• lessons/12-positioning.json — modify 5 messages

English remaining (modify → 13):

• lessons/00-basics.json — modify 4 messages
• lessons/00-basic-selectors.json — modify 15 messages
• lessons/01-advanced-selectors.json — modify 8 messages
• lessons/04-typography.json — modify 1 message
• lessons/05-units-variables.json — modify 3 messages
• lessons/06-transitions-animations.json — modify 8 messages
• lessons/07-layouts.json — modify 8 messages
• lessons/08-responsive.json — modify 8 messages
• lessons/09-gradients.json — modify 3 messages
• lessons/10-tailwind-basics.json — modify 16 messages
• lessons/11-filters.json — modify 4 messages
• lessons/13-pseudo-elements.json — modify 4 messages
• lessons/grid.json — modify 5 messages

Localized variants (modify):

• lessons/ar/flexbox.json, lessons/ar/01-box-model.json, + other ar/ modules with answer-revealing messages
• lessons/de/flexbox.json, lessons/de/01-box-model.json, + other de/ modules
• lessons/es/flexbox.json, lessons/es/01-box-model.json, + other es/ modules
• lessons/pl/flexbox.json, lessons/pl/01-box-model.json, + other pl/ modules
• lessons/uk/flexbox.json, lessons/uk/01-box-model.json, + other uk/ modules

No new files or deleted files.

4. Architecture Decisions

1. Message-only changes: Only the "message" string within validation objects is modified. The type, value, and options fields remain untouched. This preserves all validation logic.

2. No code changes to validator.js: The validator reads the message field as a passthrough string for display. No runtime changes needed.

3. Hint style per validation type:

   • property_value validations → concept question or property hint (since the property and value are tested programmatically, the message should teach the concept, not repeat the answer)
   • regex validations → directional nudge describing the expected pattern conceptually
   • contains / contains_class validations → concept question about what to include

4. Localization approach: Each localized message should be a natural translation of the English pedagogical hint, not a word-for-word translation. The hint category (question, nudge, property hint) should match the English version.

5. Preserve <kbd> tags selectively: <kbd> tags may still be used for property names (e.g., "Check the <kbd>padding</kbd> property") but never for complete property-value pairs that reveal the answer.

5. Risks

Risk	Likelihood	Mitigation
Pedagogical hints are too vague, frustrating learners	Medium	Each hint should name the relevant CSS property or concept — just not the exact value. The task description already provides context.
Localized translations lose pedagogical intent	Medium	Use consistent hint categories across languages. Review each language for natural phrasing.
Existing tests assert on specific message text	Low	Check test files for hardcoded message assertions before changing. Adjust tests if needed.
Formatting inconsistency after bulk edits	Low	Run npm run format.lessons after all changes.

6. Testing Strategy

1. Existing test suite: Run npm run test to verify no regressions. The validator tests should pass since validation logic is unchanged.
2. Grep audit: After changes, grep all lesson files for remaining "Set " patterns to confirm none were missed.
3. JSON validity: Ensure all modified JSON files parse correctly (the format.lessons command will catch syntax errors).
4. Manual spot-check: Verify a few lessons in the dev server to confirm messages display correctly in the UI.