Skip to content

Issue #32: category scope — M1/M2/M3 roster

  • Issue: #32
  • Started: 2026-04-28
  • Completed: in progress

Goal

Decide which product categories ship in M1, M2, and M3 — and record the decision so #28 page design, #33 per-category criteria, #29 DB scale, #31 canonical catalog, #24 laptops, and #25 prebuilts can build against a fixed roster instead of an open question. Two-track model from ADR-0005 makes this load-bearing: Builder track has the 8 PC components; Casual track needs a different category set (laptops, prebuilts, peripherals) that is currently M3-deferred. The decision must place every persona-anchored, retailer-stocked category somewhere on the timeline or explicitly out of scope.

Out of scope

  • No code or schema migration. If a schema change is implied (e.g. adding a MONITOR enum value), file a follow-up issue and reference it. The ADR may recommend schema work but does not perform it.
  • No re-research of personas, competitors, or retailers. personas.md, competitive-landscape.md, and retailers.md are the empirical floor. This plan synthesizes; it doesn't re-derive.
  • No new use-case anchors. UC-9 (Builder track) and UC-13 (Casual track) are already locked by ADR-0005. This plan slots categories into those tracks; it doesn't redesign the use-case model.
  • No feature roadmap. #28 page design consumes the category roster; it doesn't get drafted here.
  • No retailer-onboarding scope. #20 handles that. We describe which categories the audited retailers stock; we don't pick scrapers.

Approach

Synthesize-and-decide, single pass, no parallel-agent fan-out. Reasoning:

A per-category subagent would re-extract data already structured in those docs. Synthesis here is judgment about milestone placement, not new research. Going direct.

The decision frame, applied to every candidate:

  1. Primary persona anchor? Does at least one persona in personas.md §6.2 rank this category as primary or secondary?
  2. Retailer coverage? Do ≥2 of the 3 currently-scraped retailers carry it (or ≥3 of the H-tier next-wave picks per retailers.md §3)?
  3. Track fit? Builder (compat-checked components), Casual (single-item brand-first buy), or split?
  4. Spec-dictionary cost? How much new #33 work does this category trigger?

A category that fails (1) or (2) goes Out of scope. A category that passes both goes M1, M2, or M3 based on (3) and (4).

Steps

  • Step 1: Read the empirical floor
  • Re-read retailers.md per-retailer category lists, personas.md §6.2, competitive-landscape.md §3, use-cases.md, ADR-0005, and prisma/schema.prisma to confirm the current Category enum (10 values: 8 Builder + LAPTOP + PREBUILT).

  • Verification: every category candidate in the ticket has a row in personas.md §6.2 and a coverage signal in retailers.md.

  • Step 2: Score every candidate against the decision frame

  • For each of: monitors, laptops, prebuilts, peripherals (kbd/mice/headsets), gaming chairs, networking gear, accessories/cables — and the 8 already-shipping Builder components — record (persona anchor, retailer coverage, track fit, spec-dictionary cost) inline in the ADR's per-category rationale.

  • Verification: each candidate has a clear M1 / M2 / M3 / Out-of-scope landing, justified.

  • Step 3: Draft the ADR

  • Write docs/adr/0010-category-scope-m1-m2-m3.md from _template.md. Include:
    • Context: two-track model + persona evidence + retailer coverage + the schema enum already has LAPTOP/PREBUILT pre-allocated (seed seeds only the 8).
    • Decision: M1 = 8 Builder components (no change). M2 = monitors (preliminary recommendation; flag as the strategic call MASTER may override). M3 = laptops, prebuilts, peripherals. Out of scope = gaming chairs, networking gear, accessories/cables, mining hardware, used market.
    • Consequences: positive / negative / neutral.
    • Alternatives: "ship laptops in M2", "drop prebuilts entirely", "monitors in M3", "peripherals in M2 alongside monitors" — each with rejection reason.

  • Verification: every M2/M3 placement has a persona citation + retailer-coverage citation; every Out-of-scope has a reason that doesn't contradict personas/competitive/retailers.

  • Step 4: Write the per-category reference doc

  • Create docs/reference/categories.md with a per-category profile: scope, key spec dimensions, canonical product shape, retailer coverage in the audited roster, primary + secondary personas, milestone target. Same format as competitive-landscape.md per-competitor profiles so it reads as a peer.
  • Categories covered: the 8 Builder components, plus monitors, laptops, prebuilts, peripherals (the M2/M3 set), plus a "Deliberately out of scope" subsection covering gaming chairs / networking / accessories / mining / used.

  • Verification: every category in the ADR's decision section has a corresponding row here; no orphans.

  • Step 5: Update use-cases.md

  • Add the agreed M2/M3 categories to UC-9's "Builder track" + UC-13's "Casual track" sub-bullets in docs/architecture/use-cases.md, with milestone tags. Keep ADR-0005's framing intact.

  • Verification: UC-9 lists CPU/GPU/MB/RAM/PSU/case/cooler/storage (all M1) plus monitors (M2 — note dual-track membership). UC-13 lists laptops/prebuilts/peripherals (all M3) plus monitors (M2).

  • Step 6: Update data-model.md

  • Note in the Category enum class-diagram block that MONITOR is the planned M2 enum addition (with reference to ADR-0010). Cross-reference the new follow-up issue to be filed for the schema migration.

  • Verification: data-model.md mentions the category-scope ADR; no enum value invented in the diagram that doesn't exist in schema.prisma today (we describe the future change without making it).

  • Step 7: Cross-link from personas.md (read-only check)

  • Confirm personas.md §6.2 and personas.md §10 (downstream consumers) already reference #32 / #33; if not, do not edit personas.md silently — flag in the ADR's References section instead. (personas.md is status: active; out-of-scope edits are noise.)

  • Verification: ADR References cite personas.md; no stealth edits to personas.md.

  • Step 8: Update reference/index.md and adr/index.md

  • Add the categories.md row to docs/reference/index.md (mirror competitive-landscape.md/personas.md/retailers.md pattern).
  • Add the ADR-0010 row to docs/adr/index.md.

  • Verification: both indexes list the new artifacts.

  • Step 9: Gate — mkdocs build --strict

  • Run from project root. Any broken cross-link fails the build.

  • Verification: builds clean.

  • Step 10: Atomic commit

  • Single conventional commit covering all touched files. Message: docs(adr): add ADR-0010 category scope and per-category reference.

  • Verification: git status clean; git log -1 --stat shows only docs files.

  • Step 11: Stop

  • No push. No PR. Report commit SHA + summary + open questions to MASTER.

Risks

Risk Likelihood Mitigation
Monitor placement (M2 vs M3) is a strategic call MASTER hasn't expressed High Surface as the headline open question in the report. Provide both options with consequences. Default the ADR to M2 with explicit "MASTER may push to M3" override.
Peripherals placement (M2 alongside monitors vs M3 with laptops/prebuilts) Medium Same — surface as open question. Default M3 (lower spec-dictionary cost), flag the case for pulling forward.
ADR contradicts ADR-0005 by implying Casual track ships earlier than M3 Medium Re-read ADR-0005 line about M3-deferred catalog; treat monitors as a cross-track category rather than "Casual ships in M2." Wording matters.
Schema enum gets edited in this pass Low Constraint: "Stay in docs/. No code." Schema change becomes a referenced follow-up issue, not a step in this plan.
Out-of-scope categories (gaming chairs, networking) get re-litigated by future tickets Low The ADR's Alternatives section explicitly records why each was rejected. Future tickets re-open via supersession ADR, not by silently expanding scope.

Tests

No code changes → no test additions. The doc passes if mkdocs build --strict succeeds (Step 9 gate).

Doc updates

  • ADR: new file docs/adr/0010-category-scope-m1-m2-m3.md
  • Reference: new file docs/reference/categories.md
  • Architecture: docs/architecture/use-cases.md (UC-9 + UC-13 category lists), docs/architecture/data-model.md (Category enum note)
  • ADR index: row added in docs/adr/index.md
  • Reference index: row added in docs/reference/index.md
  • Personas: read-only check, no edits unless flagged
  • Issue body: closing comment on #32 with commit SHA + summary (deferred — gh CLI not authenticated in this session)

Rollback

git revert <sha> removes the ADR + reference doc + index updates. use-cases.md and data-model.md edits are content-additive and fully reversible. No code/state to undo.