# 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*