From 1886ac1abd77863618f20f2a8a65dda6b8ff21dc Mon Sep 17 00:00:00 2001
From: Jean-Luc Makiola <business@jeanlucmakiola.de>
Date: Sat, 14 Mar 2026 21:50:52 +0100
Subject: [PATCH] docs: define v1 requirements

---
 .planning/REQUIREMENTS.md | 97 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 97 insertions(+)
 create mode 100644 .planning/REQUIREMENTS.md

diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md
new file mode 100644
index 0000000..02d2ebb
--- /dev/null
+++ b/.planning/REQUIREMENTS.md
@@ -0,0 +1,97 @@
+# Requirements: GearBox
+
+**Defined:** 2026-03-14
+**Core Value:** Make it effortless to manage gear and plan new purchases — see how a potential buy affects your total setup weight and cost before committing.
+
+## v1 Requirements
+
+Requirements for initial release. Each maps to roadmap phases.
+
+### Collection
+
+- [ ] **COLL-01**: User can add gear items with name, weight, price, category, notes, and product link
+- [ ] **COLL-02**: User can edit and delete gear items
+- [ ] **COLL-03**: User can organize items into user-defined categories
+- [ ] **COLL-04**: User can see automatic weight and cost totals by category and overall
+
+### Planning Threads
+
+- [ ] **THRD-01**: User can create a planning thread with a name (e.g. "Helmet")
+- [ ] **THRD-02**: User can add candidate products to a thread with weight, price, notes, and product link
+- [ ] **THRD-03**: User can edit and remove candidates from a thread
+- [ ] **THRD-04**: User can resolve a thread by picking a winner, which moves to their collection
+
+### Setups
+
+- [ ] **SETP-01**: User can create named setups (e.g. "Summer Bikepacking")
+- [ ] **SETP-02**: User can add/remove collection items to a setup
+- [ ] **SETP-03**: User can see total weight and cost for a setup
+
+### Dashboard
+
+- [ ] **DASH-01**: User sees a dashboard home page with cards linking to collection, threads, and setups
+
+## v2 Requirements
+
+Deferred to future release. Tracked but not in current roadmap.
+
+### Collection Enhancements
+
+- **COLL-05**: User can upload a photo per gear item
+- **COLL-06**: User can search items by name and filter by category
+- **COLL-07**: User can choose display unit for weight (g, oz, lb, kg)
+- **COLL-08**: User can import gear from CSV file
+- **COLL-09**: User can export collection to CSV
+
+### Thread Enhancements
+
+- **THRD-05**: User can see side-by-side comparison of candidates on weight and price
+- **THRD-06**: User can track candidate status (researching → ordered → arrived)
+- **THRD-07**: User can rank/prioritize candidates within a thread
+- **THRD-08**: User can see how a candidate would affect an existing setup's weight/cost (impact preview)
+
+### Setup Enhancements
+
+- **SETP-04**: User can see weight distribution visualization (pie/bar chart by category)
+- **SETP-05**: User can classify items as base weight, worn, or consumable per setup
+
+## Out of Scope
+
+| Feature | Reason |
+|---------|--------|
+| Authentication / multi-user | Single user for v1, no login needed |
+| Custom comparison parameters | Complexity trap, weight/price covers 80% of cases |
+| Mobile native app | Web-first, responsive design sufficient |
+| Social/sharing features | Different product, defer to v2+ |
+| Price tracking / deal alerts | Requires scraping, fragile, different product category |
+| Barcode scanning / product database | Requires external database, mobile-first feature |
+| Community gear database | Requires moderation, accounts, content management |
+| Real-time weather integration | Only relevant to outdoor-specific use, GearBox is hobby-agnostic |
+
+## Traceability
+
+Which phases cover which requirements. Updated during roadmap creation.
+
+| Requirement | Phase | Status |
+|-------------|-------|--------|
+| COLL-01 | — | Pending |
+| COLL-02 | — | Pending |
+| COLL-03 | — | Pending |
+| COLL-04 | — | Pending |
+| THRD-01 | — | Pending |
+| THRD-02 | — | Pending |
+| THRD-03 | — | Pending |
+| THRD-04 | — | Pending |
+| SETP-01 | — | Pending |
+| SETP-02 | — | Pending |
+| SETP-03 | — | Pending |
+| DASH-01 | — | Pending |
+
+**Coverage:**
+- v1 requirements: 12 total
+- Mapped to phases: 0
+- Unmapped: 12 ⚠️
+
+---
+*Requirements defined: 2026-03-14*
+*Last updated: 2026-03-14 after initial definition*