HouseHoldKeaper/.planning/RETROSPECTIVE.md

Project Retrospective

A living document updated after each milestone. Lessons feed forward into future planning.

Milestone: v1.0 — MVP

Shipped: 2026-03-16 Phases: 4 | Plans: 13

What Was Built

• Complete room-based household chore app with auto-scheduling task management
• Daily plan home screen with overdue/today/tomorrow sections and progress tracking
• Bundled German task templates for 14 room types
• Daily summary notifications with configurable time and Android permission handling
• 89 tests covering DAOs, scheduling logic, providers, and widget behavior

What Worked

• Bottom-up phase structure (foundation -> data -> UI -> polish) kept each phase clean with minimal rework
• TDD approach for providers and services caught several issues early (async race conditions, API mismatches)
• Verification gates at the end of Phase 2, 3, and 4 confirmed all requirements before moving on
• Calendar-anchored scheduling with anchor memory was designed right the first time — no rework needed
• ARB localization from Phase 1 meant adding German strings was frictionless throughout

What Was Inefficient

• riverpod_generator InvalidTypeException with drift Task type required workaround (manual StreamProvider) in 3 separate plans — should have been caught in Phase 1 research
• Some plan specifications referenced outdated API patterns (flutter_local_notifications positional parameters removed in v20+) — research needs to verify exact current API signatures
• Phase 4 plan checkboxes in ROADMAP.md weren't updated to [x] by executor — minor bookkeeping gap

Patterns Established

• @Riverpod(keepAlive: true) AsyncNotifier with SharedPreferences for persistent settings (ThemeNotifier, NotificationSettingsNotifier)
• Manual StreamProvider.family/autoDispose for drift type compatibility
• DailyPlanDao innerJoin pattern for cross-table queries
• ConsumerStatefulWidget for screens with async callbacks requiring mounted guards
• Provider override pattern in widget tests for database isolation

Key Lessons

1. Research phase should verify exact current package API signatures — breaking changes between major versions cause plan deviations
2. Drift + riverpod_generator type incompatibility is a known issue — plan for manual providers from the start when using drift
3. Verification gates add minimal time (~2 min) but catch integration issues — keep them for all phases
4. Progressive disclosure (AnimatedSize) is a clean pattern for conditional settings UI

Cost Observations

• Model mix: orchestrator on opus, researchers/planners/executors/checkers on sonnet
• Total execution: ~1.3 hours for 13 plans across 4 phases
• Notable: Verification gates averaged 2 min — very efficient for the confidence they provide

---

Milestone: v1.1 — Calendar & Polish

Shipped: 2026-03-16 Phases: 3 | Plans: 5

What Was Built

• Horizontal 181-day calendar strip replacing the stacked daily plan HomeScreen
• CalendarDao with date-parameterized reactive Drift streams for day tasks and overdue tasks
• Task completion history bottom sheet with per-task reverse-chronological log
• Alphabetical, interval, and effort sort options with SharedPreferences persistence
• SortDropdown widget in both HomeScreen and TaskListScreen AppBars

What Worked

• Phase dependency ordering (5 → 6+7 parallel-capable) meant calendar strip was stable before building features on top
• TDD red-green cycle continued smoothly — every plan had failing tests before implementation
• Auto-advance mode enabled rapid phase chaining with minimal manual intervention
• Existing patterns from v1.0 (DAO, provider, widget test) were reused directly — no new patterns invented unnecessarily
• CalendarStripController (VoidCallback holder) was simpler than GlobalKey approach — good architecture call

What Was Inefficient

• StateProvider removal in Riverpod 3.x was discovered during execution rather than research — same category of issue as v1.0's riverpod_generator problem
• ROADMAP.md plan checkboxes still not auto-checked by executor (same bookkeeping gap as v1.0)
• Phase 5 plan split (data layer + UI) could have been a single plan given the small scope — overhead of 2 separate plans wasn't justified for ~13 min total

Patterns Established

• CalendarStripController: VoidCallback holder for parent-to-child imperative scroll communication
• CalendarDayList state machine: first-run → celebration → emptyDay → hasTasks (5 states)
• In-memory sort via stream.map after DB stream emit — sort preference changes without re-querying
• SortPreferenceNotifier: sync default + async _loadPersisted() — matches ThemeNotifier pattern
• Nested Scaffold pattern for per-tab AppBars in StatefulShellRoute.indexedStack

Key Lessons

1. Riverpod API surface changes (StateProvider removal) should be caught during phase research, not during execution — pattern repeats from v1.0
2. Plans under ~5 min execution can be merged into a single plan to reduce orchestration overhead
3. In-memory sort is the right approach when sort criteria don't affect DB queries — avoids re-streaming
4. Bottom sheets for one-shot modals (history) don't need dedicated Riverpod providers — ref.read() in ConsumerWidget is sufficient

Cost Observations

• Model mix: orchestrator on opus, executors/checkers on sonnet
• Total execution: ~26 min for 5 plans across 3 phases
• Notable: Each plan averaged ~5 min — significantly faster than v1.0's ~6 min average due to established patterns

---

Cross-Milestone Trends

Process Evolution

Milestone	Phases	Plans	Key Change
v1.0	4	13	Initial project — established all patterns
v1.1	3	5	Reused v1.0 patterns — faster execution, auto-advance mode

Cumulative Quality

Milestone	Tests	LOC (lib)	Key Metric
v1.0	89	7,773	dart analyze clean, 0 issues
v1.1	108	9,051	dart analyze clean, 0 issues

Top Lessons (Verified Across Milestones)

1. Research must verify current package API signatures — v1.0 hit riverpod_generator type incompatibility, v1.1 hit StateProvider removal. Same root cause: outdated API assumptions in plans.
2. Established patterns compound — v1.1 plans averaged ~5 min vs v1.0's ~6 min. Reusing DAO, provider, and test patterns eliminated design decisions.
3. Verification gates are cheap insurance — Consistently ~2 min per phase, caught regressions in both milestones.