From b2f3299d4fa4d9290673038de9003289a45b4f9b Mon Sep 17 00:00:00 2001 From: Markus Graf Date: Sun, 29 Mar 2026 10:44:49 +0200 Subject: [PATCH] docs(01): capture phase context (assumptions mode) --- .../01-grundger-st-tippmechanik/01-CONTEXT.md | 90 +++++++++++++++++++ .../01-DISCUSSION-LOG.md | 41 +++++++++ 2 files changed, 131 insertions(+) create mode 100644 .planning/phases/01-grundger-st-tippmechanik/01-CONTEXT.md create mode 100644 .planning/phases/01-grundger-st-tippmechanik/01-DISCUSSION-LOG.md diff --git a/.planning/phases/01-grundger-st-tippmechanik/01-CONTEXT.md b/.planning/phases/01-grundger-st-tippmechanik/01-CONTEXT.md new file mode 100644 index 0000000..40c0e59 --- /dev/null +++ b/.planning/phases/01-grundger-st-tippmechanik/01-CONTEXT.md @@ -0,0 +1,90 @@ +# Phase 1: Grundgerüst + Tippmechanik - Context + +**Gathered:** 2026-03-29 (assumptions mode) +**Status:** Ready for planning + + +## Phase Boundary + +Eine spielbare Tipp-Übung im Browser, die ohne API funktioniert. Umfasst: Vite-Projekt-Setup, Projektstruktur, TypeScript-Interfaces, IndexedDB-Wrapper, Screen-Management, Willkommens-Screen mit Begleitfigur/Layout-Auswahl, QWERTZ-Bildschirmtastatur mit Fingerfarben, Übungsphase "Üben" (Buchstaben einzeln tippen), adaptives Tempo, Stufen 1–6 Daten, Stufenkarte, CSS-Palette/Typografie. Kein API-Zugriff, keine Bildgenerierung, keine Begleitfigur-Dialoge. + + + +## Implementation Decisions + +### Screen Management Architecture +- **D-01:** All 5 screens (welcome, forest, lesson, reward, parent) exist as DOM containers in index.html, toggled via CSS classes with fade transitions. No dynamic DOM creation/destruction. Each screen is a `
` with a shared `.screen` class; only `.screen--active` is visible. + +### IndexedDB Schema +- **D-02:** Create the full IndexedDB schema with all 5 stores (progress, companionAssets, styleReference, forestElements, settings) in Phase 1. Only `progress` and `settings` get full read/write methods; other stores are structurally defined but unused until Phase 2+. This avoids painful version migrations later. + +### Typing Exercise Scope +- **D-03:** Phase 1 implements only the "Üben" (practice) phase — single letters appearing one at a time, typed by the child. "Entdecken" (TYPE-05) and "Wörter bauen" (TYPE-06) are Phase 3 scope. The lesson screen shows only the practice flow. +- **D-04:** A lesson consists of 8–12 random letters from the current level's key set. After all letters are correctly typed, the lesson is complete. No timer visible to the child. + +### Companion Placeholders +- **D-05:** Welcome screen uses emoji placeholders (🧚 🦄 🦊 🦉) with character names for companion selection. No companion figure appears during typing exercise. Real generated avatars replace these in Phase 2 (ASST-03). + +### Level Progression +- **D-06:** Levels 1–6 defined as static data with their key sets per the spec's progression table. A level counts as completed after one full playthrough (not perfection). Next level unlocks immediately. +- **D-07:** After completing a lesson, the app returns to the forest overview (Stufenkarte). No reward screen content in Phase 1 — the reward screen exists structurally but is skipped or shows a simple "Gut gemacht!" placeholder until Phase 3 adds Gemini-generated rewards. + +### Adaptive Tempo +- **D-08:** Start interval 3s. After 2 correct in sequence: -200ms (min 1.5s). After 1 error: +500ms (max 4s). Reset to 3s at start of each new lesson. + +### Claude's Discretion +- Screen transition timing and easing (CSS fade duration, easing function) +- Internal file/module organization within the spec's directory structure +- Exact DOM structure of keyboard component (divs vs buttons, row grouping) +- Test coverage scope — focus on typing logic and level progression, not DOM rendering + + + +## Canonical References + +**Downstream agents MUST read these before planning or implementing.** + +- `SPEC.md` — Full specification (sections 0–16), THE authoritative source for all design decisions +- `SPEC.md` section 4.1 — Level progression table (keys per level, finger assignments) +- `SPEC.md` section 6.2 — Tech stack decisions (all final) +- `SPEC.md` section 6.3 — IndexedDB store definitions +- `SPEC.md` section 7.2 — CSS color palette and typography +- `SPEC.md` section 8 — Keyboard layout, finger mapping, DE/CH differences +- `SPEC.md` section 13 — Project structure (directories + files) +- `.planning/REQUIREMENTS.md` — Phase 1 requirements: FNDN-01–05, ONBD-01–04, KYBD-01–05, TYPE-01–04, LEVL-01–03, FRST-04–05, PLSH-06 +- `public/config.json` — Gemini API key and model names (not used in Phase 1 but structure exists) + + + +## Existing Code Insights + +### Reusable Assets +No existing code — greenfield project. The only assets are: +- `public/config.json` with Gemini API key and model names +- `public/config.expample.json` as template + +### Established Patterns +None yet — Phase 1 establishes all patterns. The spec mandates: +- Vanilla TypeScript, no framework +- Single `main.css` with CSS Custom Properties +- Biome for lint/format, Vitest for tests +- Vite 6.x with vanilla-ts template + +### Integration Points +- `public/config.json` — Phase 2 will read this for API access; Phase 1 should not depend on it +- IndexedDB stores — Phase 2+ will use companionAssets, styleReference, forestElements stores created here +- Screen management — Phase 3 will add dynamic content to forest and reward screens +- Keyboard component — Phase 3 "Entdecken" phase will highlight keys for new letter introduction + + + +## Specific Ideas + +No specific requirements — open to standard approaches + + + +## Deferred Ideas + +None — analysis stayed within phase scope + diff --git a/.planning/phases/01-grundger-st-tippmechanik/01-DISCUSSION-LOG.md b/.planning/phases/01-grundger-st-tippmechanik/01-DISCUSSION-LOG.md new file mode 100644 index 0000000..bdd5b35 --- /dev/null +++ b/.planning/phases/01-grundger-st-tippmechanik/01-DISCUSSION-LOG.md @@ -0,0 +1,41 @@ +# Phase 1: Grundgerüst + Tippmechanik - Discussion Log (Assumptions Mode) + +> **Audit trail only.** Do not use as input to planning, research, or execution agents. +> Decisions captured in CONTEXT.md — this log preserves the analysis. + +**Date:** 2026-03-29 +**Phase:** 01-Grundgerüst + Tippmechanik +**Mode:** assumptions +**Areas analyzed:** Screen Management Architecture, IndexedDB Schema, Typing Exercise Scope, Companion Placeholders, Level Progression, Adaptive Tempo + +## Assumptions Presented + +### Screen Management Architecture +| Assumption | Confidence | Evidence | +|------------|-----------|----------| +| All 5 screens as DOM containers, toggled via CSS classes with fade transitions | Likely | SPEC.md line 929: "5 Screens, nur einer sichtbar, Transitions mit CSS fade" | + +### IndexedDB Schema +| Assumption | Confidence | Evidence | +|------------|-----------|----------| +| Create full schema with all 5 stores upfront, only implement read/write for progress + settings | Confident | FNDN-04 in REQUIREMENTS.md: "IndexedDB-Wrapper mit allen Stores" | + +### Typing Exercise Scope +| Assumption | Confidence | Evidence | +|------------|-----------|----------| +| Only "Üben" phase implemented; "Entdecken" and "Wörter bauen" deferred to Phase 3 | Confident | TYPE-05, TYPE-06, TYPE-07 mapped to Phase 3 in REQUIREMENTS.md | + +### Companion Placeholders +| Assumption | Confidence | Evidence | +|------------|-----------|----------| +| Emoji placeholders for companion selection, no companion during typing | Likely | SPEC.md line 930: "Platzhalter-Emojis"; ASST-03/04 mapped to Phase 2 | + +## Corrections Made + +No corrections — all assumptions confirmed. + +## External Research Flagged + +- Vite 6.x vanilla-ts template defaults and tsconfig +- Biome configuration for TypeScript strict + Vite +- IndexedDB wrapper approach: custom vs `idb` library