docs(02): capture phase context
This commit is contained in:
101
.planning/phases/02-planning-threads/02-CONTEXT.md
Normal file
101
.planning/phases/02-planning-threads/02-CONTEXT.md
Normal file
@@ -0,0 +1,101 @@
|
|||||||
|
# Phase 2: Planning Threads - Context
|
||||||
|
|
||||||
|
**Gathered:** 2026-03-15
|
||||||
|
**Status:** Ready for planning
|
||||||
|
|
||||||
|
<domain>
|
||||||
|
## Phase Boundary
|
||||||
|
|
||||||
|
Purchase research workflow: create planning threads, add candidate products, compare them, and resolve a thread by picking a winner that moves into the collection. No setups, no dashboard, no impact preview — those are later phases or v2.
|
||||||
|
|
||||||
|
</domain>
|
||||||
|
|
||||||
|
<decisions>
|
||||||
|
## Implementation Decisions
|
||||||
|
|
||||||
|
### Thread List View
|
||||||
|
- Card-based layout, same visual pattern as collection items
|
||||||
|
- Thread card shows: name prominent, then pill/chip tags for candidate count, creation date, price range
|
||||||
|
- Flat list, most recent first (no grouping)
|
||||||
|
- Resolved/archived threads hidden by default with a toggle to show them
|
||||||
|
|
||||||
|
### Candidate Display & Management
|
||||||
|
- Candidates displayed as card grid within a thread (same card style as collection items)
|
||||||
|
- Slide-out panel for adding/editing candidates (reuses existing SlideOutPanel component)
|
||||||
|
- Candidates share the exact same fields as collection items: name, weight, price, category, notes, product link, image
|
||||||
|
- Same data shape means resolution is seamless — candidate data maps directly to a collection item
|
||||||
|
|
||||||
|
### Thread Resolution Flow
|
||||||
|
- Picking a winner auto-creates a collection item from the candidate's data (no review/edit step)
|
||||||
|
- Confirmation dialog before resolving ("Pick [X] as winner? This will add it to your collection.")
|
||||||
|
- After resolution, thread is archived (removed from active list, kept in history)
|
||||||
|
- Confirmation dialog reuses the existing ConfirmDialog component pattern
|
||||||
|
|
||||||
|
### Navigation
|
||||||
|
- Tab within the collection page: "My Gear" | "Planning" tabs
|
||||||
|
- Top navigation bar always visible for switching between major sections
|
||||||
|
- Thread list and collection share the same page with tab-based switching
|
||||||
|
|
||||||
|
### Claude's Discretion
|
||||||
|
- Exact "pick winner" UX (button on card vs thread-level action)
|
||||||
|
- Thread detail page layout (how the thread view is structured beyond the card grid)
|
||||||
|
- Empty state for threads (no threads yet) and empty thread (no candidates yet)
|
||||||
|
- How the tab switching integrates with TanStack Router (query params vs nested routes)
|
||||||
|
- Thread card image (first candidate's image, thread-specific image, or none)
|
||||||
|
|
||||||
|
</decisions>
|
||||||
|
|
||||||
|
<specifics>
|
||||||
|
## Specific Ideas
|
||||||
|
|
||||||
|
- Visual consistency is important — threads and candidates should look and feel like the collection, not a separate app
|
||||||
|
- Pill/chip tag pattern carries over: candidate count, date, price range displayed as compact tags
|
||||||
|
- The slide-out panel pattern from Phase 1 should be reused directly for candidate add/edit
|
||||||
|
- Thread resolution is a one-step action: confirm → item appears in collection, thread archived
|
||||||
|
|
||||||
|
</specifics>
|
||||||
|
|
||||||
|
<code_context>
|
||||||
|
## Existing Code Insights
|
||||||
|
|
||||||
|
### Reusable Assets
|
||||||
|
- `SlideOutPanel.tsx`: Right-side slide panel — reuse for candidate add/edit
|
||||||
|
- `ConfirmDialog.tsx`: Confirmation modal — reuse for resolution confirmation
|
||||||
|
- `ItemCard.tsx`: Card component with tag chips — pattern reference for thread/candidate cards
|
||||||
|
- `ItemForm.tsx`: Form with category picker — candidate form shares the same fields
|
||||||
|
- `CategoryPicker.tsx`: ARIA combobox — reuse for candidate category selection
|
||||||
|
- `ImageUpload.tsx`: Image upload component — reuse for candidate images
|
||||||
|
- `TotalsBar.tsx`: Sticky totals — could adapt for thread-level candidate totals
|
||||||
|
|
||||||
|
### Established Patterns
|
||||||
|
- Service layer with DB injection for testability (item.service.ts, category.service.ts)
|
||||||
|
- Hono routes with Zod validation via @hono/zod-validator
|
||||||
|
- TanStack Query hooks for data fetching (useItems, useCategories, useTotals)
|
||||||
|
- Zustand store for UI state (uiStore.ts)
|
||||||
|
- API client utilities (apiGet, apiPost, apiPut, apiDelete, apiUpload)
|
||||||
|
- Shared Zod schemas in src/shared/schemas.ts
|
||||||
|
- Weight stored in grams, price in cents (integer math)
|
||||||
|
|
||||||
|
### Integration Points
|
||||||
|
- Database: Need new tables for threads and thread_candidates (src/db/schema.ts)
|
||||||
|
- Shared schemas: Need thread and candidate Zod schemas (src/shared/schemas.ts)
|
||||||
|
- Server: New routes mounted in src/server/index.ts
|
||||||
|
- Client: New route/tab integrated via TanStack Router
|
||||||
|
- Resolution creates items via existing item.service.ts createItem function
|
||||||
|
|
||||||
|
</code_context>
|
||||||
|
|
||||||
|
<deferred>
|
||||||
|
## Deferred Ideas
|
||||||
|
|
||||||
|
- Linking existing collection items as reference candidates in a thread — nice-to-have, not v1
|
||||||
|
- Side-by-side comparison view (columns instead of cards) — could be v2 enhancement (THRD-05)
|
||||||
|
- Status tracking on candidates (researching → ordered → arrived) — v2 (THRD-06)
|
||||||
|
- Impact preview showing how a candidate affects setup weight/cost — v2 (THRD-08)
|
||||||
|
|
||||||
|
</deferred>
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
*Phase: 02-planning-threads*
|
||||||
|
*Context gathered: 2026-03-15*
|
||||||
Reference in New Issue
Block a user