diff --git a/specs/004-pedagogical-messages/plan.md b/specs/004-pedagogical-messages/plan.md new file mode 100644 index 0000000..29f09b6 --- /dev/null +++ b/specs/004-pedagogical-messages/plan.md @@ -0,0 +1,87 @@ +# 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 `` tags selectively:** `` tags may still be used for property names (e.g., "Check the `padding` 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. diff --git a/specs/004-pedagogical-messages/spec.md b/specs/004-pedagogical-messages/spec.md new file mode 100644 index 0000000..a8271e3 --- /dev/null +++ b/specs/004-pedagogical-messages/spec.md @@ -0,0 +1,50 @@ +# fix: validation error messages reveal the solution instead of guiding learning + +**Issue:** [#4](https://git.librete.ch/libretech/code-crispies/issues/4) +**Repository:** libretech/code-crispies +**Author:** libretech +**State:** open +**Labels:** none + +## Issue Body + +Pedagogy audit: 88% of exercises reveal the answer in error messages, creating a fail-then-copy loop. Change validation messages from 'Set padding: 1rem' to 'Which property adds space between content and the element edge?' This applies across all modules — start with flexbox, box-model, and colors (the 3 worst offenders). + +## Acceptance Criteria + +1. Validation error messages in **flexbox**, **box-model**, and **colors** modules must no longer reveal the exact CSS property-value answer +2. Replacement messages should use pedagogical hints: concept questions, property-name hints, or directional guidance — never the literal solution +3. All remaining English lesson modules with answer-revealing messages must also be rewritten +4. Localized variants (ar/, de/, es/, pl/, uk/) of affected modules must be updated with equivalent pedagogical messages in each language +5. Existing validations (type, value, options) must remain unchanged — only the `"message"` field is modified +6. All existing tests must continue to pass + +## Scope + +### English priority modules (100% answer-revealing): +- `lessons/flexbox.json` — 6 messages +- `lessons/01-box-model.json` — 10 messages +- `lessons/03-colors.json` — 4 messages +- `lessons/12-positioning.json` — 5 messages + +### English remaining modules (partial answer-revealing): +- `lessons/00-basics.json` — 4 of 26 +- `lessons/00-basic-selectors.json` — 15 of 18 +- `lessons/01-advanced-selectors.json` — 8 of 49 +- `lessons/04-typography.json` — 1 of 9 +- `lessons/05-units-variables.json` — 3 of 5 +- `lessons/06-transitions-animations.json` — 8 of 13 +- `lessons/07-layouts.json` — 8 of 11 +- `lessons/08-responsive.json` — 8 of 10 +- `lessons/09-gradients.json` — 3 of 7 +- `lessons/10-tailwind-basics.json` — 16 of 17 +- `lessons/11-filters.json` — 4 of 7 +- `lessons/13-pseudo-elements.json` — 4 of 8 +- `lessons/grid.json` — 5 of 9 + +### Localized variants (each language directory): +- `lessons/ar/` — Arabic +- `lessons/de/` — German +- `lessons/es/` — Spanish +- `lessons/pl/` — Polish +- `lessons/uk/` — Ukrainian diff --git a/specs/004-pedagogical-messages/tasks.md b/specs/004-pedagogical-messages/tasks.md new file mode 100644 index 0000000..60f285b --- /dev/null +++ b/specs/004-pedagogical-messages/tasks.md @@ -0,0 +1,39 @@ +# Tasks + +## Phase 1: Preparation +- [ ] Task 1.1: Audit existing tests for hardcoded validation message assertions; note any that need updating +- [ ] Task 1.2: Read each priority English module and draft replacement messages using the hint style guide (concept question / property hint / directional nudge) + +## Phase 2: English Priority Modules (100% answer-revealing) +- [ ] Task 2.1: Rewrite validation messages in `lessons/flexbox.json` (6 messages) [P] +- [ ] Task 2.2: Rewrite validation messages in `lessons/01-box-model.json` (10 messages) [P] +- [ ] Task 2.3: Rewrite validation messages in `lessons/03-colors.json` (4 messages) [P] +- [ ] Task 2.4: Rewrite validation messages in `lessons/12-positioning.json` (5 messages) [P] + +## Phase 3: English Remaining Modules +- [ ] Task 3.1: Rewrite messages in `lessons/00-basic-selectors.json` (15 messages) [P] +- [ ] Task 3.2: Rewrite messages in `lessons/00-basics.json` (4 messages) [P] +- [ ] Task 3.3: Rewrite messages in `lessons/01-advanced-selectors.json` (8 messages) [P] +- [ ] Task 3.4: Rewrite messages in `lessons/04-typography.json` (1 message) [P] +- [ ] Task 3.5: Rewrite messages in `lessons/05-units-variables.json` (3 messages) [P] +- [ ] Task 3.6: Rewrite messages in `lessons/06-transitions-animations.json` (8 messages) [P] +- [ ] Task 3.7: Rewrite messages in `lessons/07-layouts.json` (8 messages) [P] +- [ ] Task 3.8: Rewrite messages in `lessons/08-responsive.json` (8 messages) [P] +- [ ] Task 3.9: Rewrite messages in `lessons/09-gradients.json` (3 messages) [P] +- [ ] Task 3.10: Rewrite messages in `lessons/10-tailwind-basics.json` (16 messages) [P] +- [ ] Task 3.11: Rewrite messages in `lessons/11-filters.json` (4 messages) [P] +- [ ] Task 3.12: Rewrite messages in `lessons/13-pseudo-elements.json` (4 messages) [P] +- [ ] Task 3.13: Rewrite messages in `lessons/grid.json` (5 messages) [P] + +## Phase 4: Localized Variants +- [ ] Task 4.1: Update Arabic (ar/) localized modules with pedagogical messages [P] +- [ ] Task 4.2: Update German (de/) localized modules with pedagogical messages [P] +- [ ] Task 4.3: Update Spanish (es/) localized modules with pedagogical messages [P] +- [ ] Task 4.4: Update Polish (pl/) localized modules with pedagogical messages [P] +- [ ] Task 4.5: Update Ukrainian (uk/) localized modules with pedagogical messages [P] + +## Phase 5: Validation & Polish +- [ ] Task 5.1: Run `npm run format.lessons` to ensure JSON formatting consistency +- [ ] Task 5.2: Run `npm run test` and fix any test failures related to message text assertions +- [ ] Task 5.3: Grep audit — verify no "Set " answer-revealing patterns remain in any lesson file +- [ ] Task 5.4: Spot-check a few lessons via `npm start` to confirm messages render correctly in the UI