# Project Retrospective

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

## Milestone: v1.0 — UI/UX Overhaul

**Shipped:** 2026-03-24
**Phases:** 4 | **Plans:** 10 | **Tasks:** 19

### What Was Built
- OKLCH design system with two-tier category colors and semantic budget status tokens
- Three chart types (expense donut, income bar, spend horizontal bar) with CSS variable theming
- URL-based month navigation with MonthNavigator dropdown
- Collapsible per-category dashboard sections with direction-aware diff and CSS animations
- PageShell, StatCard, SummaryStrip shared components for consistent page structure
- All 9 pages upgraded with consistent design, skeleton loading, and full i18n

### What Worked
- 4-phase dependency chain (foundation → charts → collapsibles → full-app) prevented rework
- Research-first approach documented Recharts v3 patch and OKLCH patterns before planning
- Pure presentational components (CategorySection, charts) made integration straightforward
- Two-tier color approach (dark text, light fills) solved WCAG contrast without sacrificing aesthetics

### What Was Inefficient
- Plan 02-01 SUMMARY.md was never written, requiring retroactive artifact creation
- Roadmap progress table fell out of sync (phases 3-4 completed but not marked in roadmap)
- Divergence between local and remote branches required hard reset — lost v1.1 milestone work

### Patterns Established
- OKLCH two-tier pattern: ~0.55 lightness for text (WCAG), ~0.65-0.70 for chart fills
- PageShell + skeleton pattern: every page gets PageShell header and matching skeleton
- Direction-aware diff: SPENDING_TYPES array + isSpendingType() covers all 6 category types
- Controlled collapsible state: parent owns open/close for smart defaults and month-change reset
- Auth card accent: border-t-4 border-t-primary + favicon logo

### Key Lessons
1. Always verify remote state before starting new local work to avoid divergence
2. Summary artifacts must be written immediately — retroactive creation loses context
3. Roadmap progress tracking should be verified at milestone completion, not assumed correct

### Cost Observations
- Model mix: 100% quality profile (opus executors, sonnet verifiers)
- Sessions: ~4-5 across the milestone
- Notable: 10 plans across 4 phases completed in ~20 days with minimal rework

---

## Cross-Milestone Trends

### Process Evolution

| Milestone | Phases | Plans | Key Change |
|-----------|--------|-------|------------|
| v1.0 UI/UX | 4 | 10 | First GSD milestone on this project; research-first approach |

### Top Lessons (Verified Across Milestones)

1. Research before planning eliminates mid-phase surprises
2. Foundation-first phasing (tokens → components → integration) prevents rework