In-repo knowledge base for product decisions, design specs, and implementation plans. Versioned with the code so every branch carries the context it needs.
Rule: code wins on conflict. If a spec and the code disagree, the code is the truth. Update the spec, not the code.
| Folder | What goes here |
|---|---|
docs/specs/ |
Design specs — what to build and why; decisions locked before implementation |
docs/plans/ |
Implementation plans — how to phase an epic into tickets |
docs/adr/ |
Architecture decision records — why a specific technical choice was made (create when needed) |
Naming convention: YYYY-MM-DD-<slug>.md
Every doc carries a **Status:** header. Valid values:
| Status | Meaning |
|---|---|
draft |
Work in progress; not yet reviewed |
active |
Current and authoritative |
implemented |
Feature shipped; doc is now historical reference |
superseded |
Replaced by a newer doc — header must link to the replacement |
| Doc | Description | Status |
|---|---|---|
| Visual Identity System | Refined-industrial visual direction, per-pillar color system, type stack | active |
| Information Architecture | Three-tier access architecture, sitemap, navigation model | active |
| Friends, Presence & Messaging | Social layer: friend lists, online presence, in-app chat | active |
| Notifications & Push | In-app stack + web push (VAPID), per-group notification levels, per-pillar taxonomy | active |
| S.P.O.I.L.S. | Loot settlement: hybrid fairness ledger, QM roles, 5-state lifecycle, UEX pricing | active |
| Doc | Description | Status |
|---|---|---|
| Friends & Presence Epic 1 Plan | Phase breakdown and ticket map for Epic 1 (friends + presence foundation) | active |
- Pick the right type (
specs/,plans/,adr/) - Name it
YYYY-MM-DD-<slug>.md - Open with
**Date:**,**Author:**,**Status:** draft - Add a row to the index above
- Change status to
activewhen reviewed and approved