From 71312b112216a2331f57b3d57c74ebb2bd3d7f15 Mon Sep 17 00:00:00 2001 From: Jean-Luc Makiola Date: Sun, 15 Mar 2026 19:34:42 +0100 Subject: [PATCH] docs(phase-1): add context, research, and validation strategy --- .../phases/01-foundation/01-VALIDATION.md | 81 ++++++++++++++++ .planning/phases/01-foundation/1-CONTEXT.md | 92 +++++++++++++++++++ 2 files changed, 173 insertions(+) create mode 100644 .planning/phases/01-foundation/01-VALIDATION.md create mode 100644 .planning/phases/01-foundation/1-CONTEXT.md diff --git a/.planning/phases/01-foundation/01-VALIDATION.md b/.planning/phases/01-foundation/01-VALIDATION.md new file mode 100644 index 0000000..15bd912 --- /dev/null +++ b/.planning/phases/01-foundation/01-VALIDATION.md @@ -0,0 +1,81 @@ +--- +phase: 1 +slug: foundation +status: draft +nyquist_compliant: false +wave_0_complete: false +created: 2026-03-15 +--- + +# Phase 1 — Validation Strategy + +> Per-phase validation contract for feedback sampling during execution. + +--- + +## Test Infrastructure + +| Property | Value | +|----------|-------| +| **Framework** | flutter_test (bundled with Flutter SDK) | +| **Config file** | none — Wave 0 creates test scaffolding | +| **Quick run command** | `flutter test` | +| **Full suite command** | `flutter test --coverage` | +| **Estimated runtime** | ~10 seconds | + +--- + +## Sampling Rate + +- **After every task commit:** Run `flutter test` +- **After every plan wave:** Run `flutter test --coverage` +- **Before `/gsd:verify-work`:** Full suite must be green + `dart analyze` clean (zero riverpod_lint issues) +- **Max feedback latency:** 15 seconds + +--- + +## Per-Task Verification Map + +| Task ID | Plan | Wave | Requirement | Test Type | Automated Command | File Exists | Status | +|---------|------|------|-------------|-----------|-------------------|-------------|--------| +| TBD | 01 | 0 | FOUND-01 | unit + smoke | `flutter test test/core/database/database_test.dart` | No — Wave 0 | ⬜ pending | +| TBD | 01 | 0 | FOUND-02 | smoke | `dart analyze` | No — Wave 0 | ⬜ pending | +| TBD | 01 | 0 | FOUND-03 | widget | `flutter test test/l10n/localization_test.dart` | No — Wave 0 | ⬜ pending | +| TBD | 01 | 0 | FOUND-04 | widget | `flutter test test/shell/app_shell_test.dart` | No — Wave 0 | ⬜ pending | +| TBD | 01 | 0 | THEME-01 | widget | `flutter test test/core/theme/theme_test.dart` | No — Wave 0 | ⬜ pending | +| TBD | 01 | 0 | THEME-02 | unit | `flutter test test/core/theme/color_scheme_test.dart` | No — Wave 0 | ⬜ pending | + +*Status: ⬜ pending · ✅ green · ❌ red · ⚠️ flaky* + +--- + +## Wave 0 Requirements + +- [ ] `test/core/database/database_test.dart` — covers FOUND-01 (database opens, schema version correct) +- [ ] `test/l10n/localization_test.dart` — covers FOUND-03 (German strings load from ARB) +- [ ] `test/shell/app_shell_test.dart` — covers FOUND-04 (navigation bar renders 3 tabs) +- [ ] `test/core/theme/theme_test.dart` — covers THEME-01 (light/dark/system switching) +- [ ] `test/core/theme/color_scheme_test.dart` — covers THEME-02 (sage green seed, warm surfaces) +- [ ] Drift migration test scaffolding via `dart run drift_dev make-migrations` (auto-generated) + +--- + +## Manual-Only Verifications + +| Behavior | Requirement | Why Manual | Test Instructions | +|----------|-------------|------------|-------------------| +| Warm dark mode visual appearance | THEME-02 | Color perception is subjective — hex values pass tests but need visual review | Launch app, toggle to dark mode, verify charcoal-brown feel (not cold/blue-gray) | +| Thematic tab icons look correct | FOUND-04 | Icon selection is a design judgment | Launch app, verify clipboard/door/sliders icons match household domain | + +--- + +## Validation Sign-Off + +- [ ] All tasks have `` verify or Wave 0 dependencies +- [ ] Sampling continuity: no 3 consecutive tasks without automated verify +- [ ] Wave 0 covers all MISSING references +- [ ] No watch-mode flags +- [ ] Feedback latency < 15s +- [ ] `nyquist_compliant: true` set in frontmatter + +**Approval:** pending diff --git a/.planning/phases/01-foundation/1-CONTEXT.md b/.planning/phases/01-foundation/1-CONTEXT.md new file mode 100644 index 0000000..7d8eea7 --- /dev/null +++ b/.planning/phases/01-foundation/1-CONTEXT.md @@ -0,0 +1,92 @@ +# Phase 1: Foundation - Context + +**Gathered:** 2026-03-15 +**Status:** Ready for planning + + +## Phase Boundary + +The app compiles, opens, and enforces correct architecture patterns — ready to receive features without accumulating technical debt. Delivers: project scaffold, Drift database with schema v1 and migration workflow, Riverpod 3 state management with code generation, ARB localization infrastructure (German), bottom navigation shell with three tabs, light/dark theme with calm Material 3 palette, and riverpod_lint enforcement. + +Requirements: FOUND-01, FOUND-02, FOUND-03, FOUND-04, THEME-01, THEME-02 + + + + +## Implementation Decisions + +### Color palette & theme +- **Mood:** Sage & stone — muted sage green primary, warm stone/beige surfaces, slate blue accents +- **Color density:** Color-shy — mostly neutral surfaces, color only on key interactive elements (FAB, active tab indicator, badges, buttons) +- **Light mode:** Warm stone/beige surface tones, sage green for interactive elements, slate blue for secondary accents +- **Dark mode:** Warm charcoal-brown backgrounds (not pure #121212 black) — softer on the eyes, matches the calm aesthetic +- **Material 3:** Use M3 color system with ColorScheme.fromSeed, tuning the seed and surface tints to achieve the sage & stone feel + +### Navigation & tabs +- **Icons:** Thematic — checklist/clipboard (Home/Übersicht), door (Räume), sliders (Einstellungen) +- **Labels:** German from day 1, loaded from ARB files — "Übersicht", "Räume", "Einstellungen" +- **Default tab:** Home (Übersicht) — user opens the app and immediately sees the daily plan view +- **Active tab style:** Standard Material 3 behavior — filled icon + indicator pill, using the sage green palette via the M3 color system + +### Placeholder screens +- **Tone:** Playful & light — touch of humor, emoji-friendly German text +- **Visual pattern:** Material icon + playful message + action button (consistent across all empty states) +- **Home empty state:** Guides user to Rooms tab — e.g. "Noch nichts zu tun 🎉 — lege zuerst einen Raum an!" with button navigating to Räume tab +- **Rooms empty state:** Encourages creating first room — e.g. "Hier ist noch alles leer 🏠 — erstelle deinen ersten Raum!" with create room button +- **All empty state text:** Loaded from ARB localization files, not hardcoded + +### Settings screen +- **Content in Phase 1:** Working theme switcher (System/Hell/Dunkel) + About section (app name, version, one-liner tagline) +- **Layout:** Grouped with section headers — "Darstellung" (theme) and "Über" (about) — structured and ready for future settings +- **About section:** App name "HouseHoldKeaper", version number, short tagline (e.g. "Dein Haushalt, entspannt organisiert.") +- **Language setting:** Hidden — not shown until English lands in v1.1 +- **All labels:** From ARB localization files + +### Claude's Discretion +- Theme picker widget style (segmented button, dropdown, or bottom sheet — pick best M3 pattern) +- Exact icon choices for thematic tab icons (pick from Material Icons set, matching the household domain) +- Loading skeleton and transition animations +- Exact spacing, typography scale, and component sizing +- Error state designs (network errors won't apply, but database/initialization errors) + + + + +## Specific Ideas + +- Sage & stone palette is inspired by "a calm kitchen with natural materials" — not clinical white, not forest dark +- Empty states should feel friendly, not corporate — emoji usage is encouraged +- The Home tab empty state must cross-navigate to the Rooms tab (not just display text) +- Settings should feel like a complete screen even with minimal content — section headers give it structure +- Tagline vibe: "Dein Haushalt, entspannt organisiert." (Your household, calmly organized) + + + + +## Existing Code Insights + +### Reusable Assets +- None — greenfield project, no existing code beyond LICENSE and README.md + +### Established Patterns +- None yet — Phase 1 establishes all patterns for subsequent phases + +### Integration Points +- Phase 2 will build room CRUD on top of the Drift database and Riverpod providers established here +- Phase 2 will replace the Rooms placeholder screen with actual room list +- Phase 3 will replace the Home placeholder screen with the daily plan view +- Phase 4 will add notification settings to the Settings screen (into the grouped layout) + + + + +## Deferred Ideas + +None — discussion stayed within phase scope + + + +--- + +*Phase: 01-foundation* +*Context gathered: 2026-03-15*