GearBox/.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-15 Phases: 3 | Plans: 10 | Commits: 53

What Was Built

• Full gear collection with item CRUD, categories, weight/cost totals, and image uploads
• Planning threads with candidate comparison and thread resolution into collection
• Named setups (loadouts) composed from collection items with live totals
• Dashboard home page with summary cards
• Onboarding wizard for first-time user experience
• Service-level and route-level integration tests

What Worked

• Coarse 3-phase structure kept momentum high — no planning overhead between tiny phases
• TDD approach for backend (service tests first) caught issues early and made frontend integration smooth
• Service layer with DI (db as first param) made testing trivial with in-memory SQLite
• Visual verification checkpoints at end of each phase caught UI issues before moving on
• Bun + Vite + Hono stack had zero friction — everything worked together cleanly

What Was Inefficient

• Verification plans (XX-03) were mostly rubber-stamp auto-approvals in yolo mode — could skip for v2
• Some ROADMAP plan checkboxes never got checked off (cosmetic, didn't affect tracking)
• Performance metrics in STATE.md had stale placeholder data alongside real data

Patterns Established

• Service functions: (db, params) => result with production db default
• Route-level integration tests using Hono context variables for db injection
• Prices in cents everywhere, display conversion in UI only
• Tab navigation via URL search params for shareability
• Atomic sync pattern: delete-all + re-insert in transaction

Key Lessons

1. Coarse granularity (3 phases for an MVP) is the right call for a greenfield app — avoids over-planning
2. The Vite proxy pattern is required when using TanStack Router plugin — can't do Bun fullstack serving
3. drizzle-kit needs better-sqlite3 even on Bun — can't use bun:sqlite for migrations
4. Onboarding state belongs in the database (settings table), not in client-side stores

Cost Observations

• Model mix: quality profile throughout
• Sessions: ~10 plan executions across 2 days
• Notable: Most plans completed in 3-5 minutes, total wall time under 1 hour

---

Milestone: v1.1 — Fixes & Polish

Shipped: 2026-03-15 Phases: 3 | Plans: 7 | Files changed: 65

What Was Built

• Fixed threads table and thread creation with categoryId support and modal dialog
• Overhauled planning tab with educational empty state, pill tabs, and category filter
• Fixed image display bug (Zod schema missing imageFilename)
• Redesigned image upload as 4:3 hero preview area with placeholders on all cards
• Migrated categories from emoji to Lucide icons with 119-icon curated picker
• Built IconPicker with search, 8 group tabs, and portal popover

What Worked

• Auto-advance pipeline (discuss → plan → execute) completed both phases end-to-end without manual intervention
• Wave-based parallel execution in Phase 6 — plans 06-02 and 06-03 ran concurrently with no conflicts
• Executor auto-fix deviations handled cascading renames gracefully (emoji→icon required touching hooks/routes beyond plan scope)
• Context discussion upfront captured clear decisions — no ambiguity during execution
• Verifier caught real issues (Zod schema root cause) and confirmed all must-haves

What Was Inefficient

• Schema renames cascade through many files (12 in 06-01) — executors had to auto-fix downstream references not in the plan
• Some ROADMAP.md plan checkboxes remained unchecked despite plans completing (cosmetic tracking drift)
• Phase 5 executor installed inline SVGs for ImageUpload icons, then Phase 6 added lucide-react anyway — could have coordinated

Patterns Established

• Portal-based popover pattern: reused from EmojiPicker → IconPicker (click-outside, escape, portal rendering)
• LucideIcon dynamic lookup component: icons[name] from lucide-react for runtime icon resolution
• Curated icon data file pattern: static data organized by groups for picker UIs
• Hero image area: full-width 4:3 preview at top of forms with placeholder/upload/preview states

Key Lessons

1. Zod validation middleware silently strips unknown fields — always add new schema fields to Zod schemas, not just DB schema
2. Auto-fix deviations are a feature, not a bug — executors that fix cascading renames save manual replanning
3. Auto-advance pipeline works well for straightforward phases — interactive discussion ensures decisions are clear before autonomous execution
4. Parallel Wave 2 execution with no file overlap is safe and efficient

Cost Observations

• Model mix: opus for execution, sonnet for verification/checking
• Sessions: 1 continuous auto-advance pipeline for both phases
• Notable: Full milestone (discuss + plan + execute × 2 phases) completed in a single session

---

Cross-Milestone Trends

Process Evolution

Milestone	Commits	Phases	Key Change
v1.0	53	3	Initial build, coarse granularity, TDD backend
v1.1	~30	3	Auto-advance pipeline, parallel wave execution, auto-fix deviations

Cumulative Quality

Milestone	LOC	Files	Tests
v1.0	5,742	114	Service + route integration
v1.1	6,134	~130	Service + route integration (updated for icon schema)

Top Lessons (Verified Across Milestones)

1. Coarse phases with TDD backend → smooth frontend integration
2. Service DI pattern enables fast, reliable testing without mocks
3. Always update Zod schemas alongside DB schema — middleware silently strips unvalidated fields
4. Auto-advance pipeline (discuss → plan → execute) works well for clear-scope phases