docs(phase-1): add context, research, and validation strategy
This commit is contained in:
81
.planning/phases/01-foundation/01-VALIDATION.md
Normal file
81
.planning/phases/01-foundation/01-VALIDATION.md
Normal file
@@ -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 `<automated>` 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
|
||||||
92
.planning/phases/01-foundation/1-CONTEXT.md
Normal file
92
.planning/phases/01-foundation/1-CONTEXT.md
Normal file
@@ -0,0 +1,92 @@
|
|||||||
|
# Phase 1: Foundation - Context
|
||||||
|
|
||||||
|
**Gathered:** 2026-03-15
|
||||||
|
**Status:** Ready for planning
|
||||||
|
|
||||||
|
<domain>
|
||||||
|
## 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
|
||||||
|
|
||||||
|
</domain>
|
||||||
|
|
||||||
|
<decisions>
|
||||||
|
## 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)
|
||||||
|
|
||||||
|
</decisions>
|
||||||
|
|
||||||
|
<specifics>
|
||||||
|
## 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)
|
||||||
|
|
||||||
|
</specifics>
|
||||||
|
|
||||||
|
<code_context>
|
||||||
|
## 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)
|
||||||
|
|
||||||
|
</code_context>
|
||||||
|
|
||||||
|
<deferred>
|
||||||
|
## Deferred Ideas
|
||||||
|
|
||||||
|
None — discussion stayed within phase scope
|
||||||
|
|
||||||
|
</deferred>
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
*Phase: 01-foundation*
|
||||||
|
*Context gathered: 2026-03-15*
|
||||||
Reference in New Issue
Block a user