docs(quick-260329-tk2): Üben-Phase kindgerechte Erklärung

2026-03-29 21:20:37 +02:00
parent 3352f6bbb6
commit 36e71a692b
2 changed files with 82 additions and 1 deletions
@@ -5,7 +5,7 @@ milestone_name: milestone
 status: verifying
 stopped_at: Completed 04-04-PLAN.md
 last_updated: "2026-03-29T16:27:27.702Z"
-last_activity: 2026-03-29
+last_activity: 2026-03-29 - Completed quick task 260329-tk2: Üben-Phase kindgerechte Erklärung
 progress:
  total_phases: 4
  completed_phases: 4
@@ -0,0 +1,81 @@
+---
+phase: quick
+plan: 260329-tk2
+type: execute
+wave: 1
+depends_on: []
+files_modified: [src/ui/screens.ts]
+autonomous: true
+---
+
+<objective>
+Replace the bare "Ueben" and "Woerter" phase labels with child-friendly companion explanations so a 7-year-old understands what to do in each phase.
+
+Purpose: Currently the practice phase just shows "Ueben" as a heading with no explanation. The child doesn't know it should press the key matching the falling letter. Same issue for the "Woerter" phase. Adding brief companion text (like the discover phase already does) makes each phase self-explanatory.
+
+Output: Updated screens.ts with companion text shown at the start of practice and words phases.
+</objective>
+
+<execution_context>
+@$HOME/.claude/get-shit-done/workflows/execute-plan.md
+@$HOME/.claude/get-shit-done/templates/summary.md
+</execution_context>
+
+<context>
+@src/ui/screens.ts (lesson screen with phase transitions)
+</context>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Add companion instructions for practice and words phases</name>
+  <files>src/ui/screens.ts</files>
+  <action>
+In `runPracticePhase()` (line ~471), after `setPhase("practice")` and before creating the exercise state, add companion text that explains what the child should do. Show the companion area and set a brief instruction text, then wait ~2500ms before starting the exercise so the child can read it.
+
+Use this pattern (matching the existing discover phase pattern):
+```typescript
+companionText.textContent = "Jetzt kannst du ueben! Druecke die Taste zu dem Buchstaben, der herunterfaellt.";
+companionArea.style.display = "flex";
+await new Promise<void>((resolve) => setTimeout(resolve, 2500));
+if (cancelled) return;
+```
+
+The function must become async (change `function runPracticePhase(): Promise<void>` to use async/await instead of wrapping in `new Promise`).
+
+Similarly, in `runWordsPhase()` (line ~479), after `setPhase("words")` and before the word logic, add:
+```typescript
+companionText.textContent = "Jetzt kommen ganze Woerter! Tippe die Buchstaben nacheinander ein.";
+companionArea.style.display = "flex";
+await new Promise<void>((resolve) => setTimeout(resolve, 2500));
+if (cancelled) return;
+```
+
+The `runWordsPhase` function is already returning a Promise — convert it to async/await as well.
+
+Important: Use ue/oe/ae transliteration for umlauts (existing codebase convention per STATE.md decisions). Keep messages short and simple for a 7-year-old. Clear companionText before starting the actual exercise (set `companionText.textContent = ""` after the delay, before `runLetterExercise`/`runWordExercise`).
+  </action>
+  <verify>
+    <automated>cd /home/dev/workspace/zauberwald && npx vitest run --reporter=verbose 2>&1 | tail -20</automated>
+  </verify>
+  <done>Practice phase shows "Jetzt kannst du ueben! Druecke die Taste zu dem Buchstaben, der herunterfaellt." before starting. Words phase shows "Jetzt kommen ganze Woerter! Tippe die Buchstaben nacheinander ein." before starting. Both messages display for ~2.5 seconds with companion avatar visible. All existing tests pass.</done>
+</task>
+
+</tasks>
+
+<verification>
+- `npx vitest run` passes with no regressions
+- `npx tsc --noEmit` compiles without errors
+- Manual: Start a lesson, observe companion text appears during practice and words phases
+</verification>
+
+<success_criteria>
+- Practice phase shows a child-friendly instruction before falling letters begin
+- Words phase shows a child-friendly instruction before word typing begins
+- Messages use simple German suitable for a 7-year-old
+- Existing companion text patterns (discover phase) are followed consistently
+</success_criteria>
+
+<output>
+After completion, create `.planning/quick/260329-tk2-ben-phase-kindgerechte-erkl-rung-statt-n/260329-tk2-SUMMARY.md`
+</output>