docs(01): capture phase context (assumptions mode)
This commit is contained in:
@@ -0,0 +1,90 @@
|
||||
# Phase 1: Grundgerüst + Tippmechanik - Context
|
||||
|
||||
**Gathered:** 2026-03-29 (assumptions mode)
|
||||
**Status:** Ready for planning
|
||||
|
||||
<domain>
|
||||
## 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.
|
||||
</domain>
|
||||
|
||||
<decisions>
|
||||
## 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 `<section>` 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
|
||||
</decisions>
|
||||
|
||||
<canonical_refs>
|
||||
## 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)
|
||||
</canonical_refs>
|
||||
|
||||
<code_context>
|
||||
## 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
|
||||
</code_context>
|
||||
|
||||
<specifics>
|
||||
## Specific Ideas
|
||||
|
||||
No specific requirements — open to standard approaches
|
||||
</specifics>
|
||||
|
||||
<deferred>
|
||||
## Deferred Ideas
|
||||
|
||||
None — analysis stayed within phase scope
|
||||
</deferred>
|
||||
@@ -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
|
||||
Reference in New Issue
Block a user