Jean-Luc Makiola
2853477a75
Phases 28-31 archived to milestones/v2.2-phases/ Requirements and roadmap snapshots archived to milestones/ Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
6.2 KiB
6.2 KiB
Requirements Archive: v2.2 User Experience Polish
Archived: 2026-04-13 Status: SHIPPED
For current requirements, see .planning/REQUIREMENTS.md.
Requirements: GearBox v2.1 Public Discovery
Defined: 2026-04-09 Core Value: Help people make better gear decisions — discover what others use, compare real-world data, and see how a potential buy affects your setup before committing.
v2.1 Requirements
Requirements for Public Discovery milestone. Each maps to roadmap phases.
Public Access
- PUBL-01: User can browse the global item catalog without logging in
- PUBL-02: User can view public setups without logging in
- PUBL-03: User can view user profiles without logging in
- PUBL-04: Anonymous visitors see the landing page without auth spinner or redirect
- PUBL-05: Login is only required when user attempts to create/edit/delete their own data
Discovery
- DISC-01: Landing page displays an always-visible catalog search bar at the top
- DISC-02: Landing page shows a feed of popular setups below the search
- DISC-03: Landing page shows recently added catalog items
- DISC-04: Landing page shows trending categories
- DISC-05: Authenticated users see a "Go to Collection" entry point from the landing page
Catalog Enrichment
- CATL-01: Global items have attribution fields (sourceUrl, manufacturer, imageCredit, imageSourceUrl)
- CATL-02: Global items have a unique constraint on (brand, model) preventing duplicates
- CATL-03: Catalog detail pages display image attribution with credit and source link
- CATL-04: Bulk import API endpoint accepts multiple catalog items in one request
- CATL-05: Bulk import uses upsert semantics (ON CONFLICT update, not fail)
Agent Seeding Tools
- SEED-01: MCP server has a dedicated
upsert_catalog_itemtool that writes to globalItems (not user-scoped) - SEED-02: MCP server has a
bulk_upsert_catalogtool for batch catalog population - SEED-03: Catalog MCP tools include attribution fields (sourceUrl, manufacturer, imageCredit) as parameters
Infrastructure
- INFR-01: Public API endpoints are rate-limited to prevent abuse
- INFR-02: Discovery feed endpoint uses cursor pagination for scalability
Future Requirements
Deferred to future milestones. Tracked but not in current roadmap.
Personalization
- PERS-01: Logged-in users see a feed tuned to their collection categories
- PERS-02: Feed algorithm recommends content based on user's hobby interests
Reviews & Content
- REVW-01: Users can write structured reviews on catalog items
- REVW-02: Reviews appear in the discovery feed
- REVW-03: Curated/linked external reviews surface in feed
SEO
- SEO-01: Catalog pages are crawlable by search engine bots
- SEO-02: Catalog pages have proper meta tags and structured data
Catalog Seeding
- SEED-04: Initial seeding run populates 100+ items across key categories via agent swarm
Reviews & Ratings (from v2.0)
- REV-01: User can rate a global item with an overall star rating
- REV-02: User can rate a global item on predefined dimensions (durability, value, etc.)
- REV-03: Item detail pages show average ratings from all reviewers
Aggregation (from v2.0)
- AGG-01: Item detail pages show crowd-verified specs (manufacturer vs community-measured weight)
- AGG-02: Item detail pages show which setups include this item
- AGG-03: Setup composition insights ("commonly paired with")
Social (from v2.0)
- SOCL-01: User can fork/copy a public setup as a template
- SOCL-02: Planning thread candidates can link to global items for auto-populated specs
- SOCL-03: User can follow other users
- SOCL-04: User can view an activity feed of followed users' content
Content Moderation (from v2.0)
- MOD-01: User can submit freeform text reviews
- MOD-02: User can report inappropriate content
- MOD-03: Admin can review and act on reported content
Out of Scope
Explicitly excluded. Documented to prevent scope creep.
| Feature | Reason |
|---|---|
| Personalized feed algorithm | Requires usage data and collection analysis — build simple feed first |
| SSR / static prerendering for SEO | Needs dedicated research on approach for TanStack Router — defer to v2.2+ |
| Freeform reviews / comments | No moderation infrastructure yet — structured UGC only |
| Admin role / permission system | Current auth model has no role distinction — API key sufficient for v2.1 |
| Image scraping automation | Legal gray area — agent seeding uses manufacturer-provided images with attribution |
| User-to-user messaging | High moderation burden, not core to discovery |
| Wiki-style open item editing | Quality control risk; structured contributions only |
| Marketplace / buy-sell | Payment processing, fraud, legal liability |
| AI gear recommendations | Training data requirements, hallucination risk |
| Gamification (badges, points) | Incentivizes quantity over quality |
| Price tracking / deal alerts | Requires scraping, fragile, legal gray area |
| Mobile native app | Web-first, responsive design sufficient |
Traceability
Which phases cover which requirements. Updated during roadmap creation.
| Requirement | Phase | Status |
|---|---|---|
| PUBL-01 | Phase 24 | Complete |
| PUBL-02 | Phase 24 | Complete |
| PUBL-03 | Phase 24 | Complete |
| PUBL-04 | Phase 24 | Complete |
| PUBL-05 | Phase 24 | Complete |
| INFR-01 | Phase 24 | Complete |
| CATL-01 | Phase 25 | Complete |
| CATL-02 | Phase 25 | Complete |
| CATL-03 | Phase 25 | Complete |
| CATL-04 | Phase 25 | Complete |
| CATL-05 | Phase 25 | Complete |
| SEED-01 | Phase 25 | Complete |
| SEED-02 | Phase 25 | Complete |
| SEED-03 | Phase 25 | Complete |
| DISC-01 | Phase 26 | Complete |
| DISC-02 | Phase 26 | Complete |
| DISC-03 | Phase 26 | Complete |
| DISC-04 | Phase 26 | Complete |
| DISC-05 | Phase 26 | Complete |
| INFR-02 | Phase 26 | Complete |
Coverage:
- v2.1 requirements: 20 total
- Mapped to phases: 20
- Unmapped: 0
Requirements defined: 2026-04-09 Last updated: 2026-04-09 after roadmap creation