makiolaj/GearBox
1
0
Fork 0
Code Issues 8 Pull Requests Actions Packages Projects Releases 3 Wiki Activity
Files
v1.2
GearBox/.planning/RETROSPECTIVE.md
Jean-Luc Makiola 4cb356d6b0 chore: archive v1.2 Collection Power-Ups milestone 
Archive roadmap and requirements to milestones/, evolve PROJECT.md
with validated requirements, update retrospective, and reorganize
ROADMAP.md with milestone groupings.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-16 19:09:13 +01:00

8.9 KiB
Raw Permalink Blame History

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

Milestone: v1.2 — Collection Power-Ups

Shipped: 2026-03-16 Phases: 3 | Plans: 6 | Files changed: 66

What Was Built

  • Weight unit conversion (g/oz/lb/kg) with segmented toggle wired across all weight display call sites
  • Candidate status tracking (researching/ordered/arrived) with clickable StatusBadge popup
  • Sticky search/filter toolbar with text search and icon-aware CategoryFilterDropdown
  • Per-setup item classification (base/worn/consumable) with click-to-cycle ClassificationBadge
  • Recharts donut chart with category/classification toggle and hover tooltips
  • Classification-preserving sync that maintains metadata across atomic setup item re-sync

What Worked

  • Coarse 3-phase structure again — 19 requirements compressed into 3 phases with clear dependency ordering
  • TDD red/green commits for schema migrations (status, classification) caught edge cases early
  • Vertical slice pattern (schema → service → tests → API → UI in one plan) kept each deliverable self-contained
  • Click-outside dismiss pattern established in v1.1 was reused cleanly in StatusBadge and CategoryFilterDropdown
  • All 6 plans executed with zero deviations from plan — evidence of mature planning process

What Was Inefficient

  • Some ROADMAP.md plan checkboxes remained unchecked despite summaries existing (persistent cosmetic drift)
  • Recharts v3 Cell component is deprecated for v4 — will need migration eventually
  • Phase 8 bundled search/filter with candidate status (different concerns) — could have been separate phases for cleaner scope

Patterns Established

  • Click-to-cycle badge: for small enums (3 values), direct click cycling is simpler than popup menus
  • Join table metadata preservation: save metadata to Map before atomic sync, restore after re-insert
  • CategoryFilterDropdown: reusable filter dropdown (separate from form-based CategoryPicker)
  • Chart data transformation: group items by key, sum weights, compute percentages, filter zeroes
  • apiPatch helper: PATCH method now available in client API library for partial updates

Key Lessons

  1. Classification belongs on join tables (setupItems), not entity tables (items) — same item has different roles in different contexts
  2. Vertical slice delivery (schema → service → test → API → UI) is the optimal plan structure for feature additions
  3. Search complexity should match data scale — no debounce needed for <1000 items
  4. Recharts composable API (PieChart + Pie + Cell + Tooltip + Label) gives fine-grained chart control with minimal wrapper code

Cost Observations

  • Model mix: quality profile throughout (opus for execution)
  • Sessions: 3 continuous auto-advance sessions (one per phase)
  • Notable: All plans completed with zero deviations, execution faster than v1.0/v1.1

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
v1.2 25 3 Zero-deviation execution, vertical slice pattern, join table metadata

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)
v1.2 7,310 ~150 121 tests (service + route + classification)

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
  5. Vertical slice delivery (schema → service → test → API → UI) is optimal for feature additions
  6. Join table metadata (not entity table) when same entity plays different roles in different contexts
Reference in New Issue View Git Blame Copy Permalink