docs/
Everything the repository knows that is not code. What the product is, who it is for, why it is built this way, what was decided, what is still open, and how to operate it when it breaks.
The organising idea is that each kind of knowledge has exactly one home, so that writing something down is never a question of taste and finding it is never a search.
What is where, and why that split
| holds | the question it answers | |
|---|---|---|
PRODUCT.md | what this is and where it is going | why does this exist |
PRINCIPLES.md | the engineering principles | what do we refuse to trade away |
ARCHITECTURE.md | structure and boundaries | how is it put together |
personas.md | the roster | who is it for |
decision-records/ | ADR and BDR | why is it like this |
conventions.md | the day-to-day rules | how do we work here |
backlog.md | intents with a definition of done | what do we still owe |
discovery/ | provenance-stamped raw material | where did this come from |
ideas/ | speculation under a status | should this exist at all |
runbooks/ | operating knowledge and postmortems | it is broken, now what |
research/, journeys/, sprints/ | evidence, paths, commitments | (scale) |
Behaviour is deliberately absent from that list. It lives in specs/, one folder up, because it is the one kind of knowledge that has to be checkable against the code.
The rule that keeps it usable
A fact has one home. A count, a version, a path, a command belongs in one file, and everywhere else links to it. Where a restatement genuinely has to exist, it gets declared in facts.json and a guard fails when the two stop agreeing.
This is not tidiness. A number repeated in three files is three things to update and one that will be wrong, and the wrong one is invisible until somebody acts on it.
What does not go in here
Anything the code already says. Documentation that restates a function signature is a second copy with a slower update sprint.
Anything with no home in the table above. If you cannot say which row it belongs to, that is the useful signal: the standard's taxonomy exists to answer exactly that question, and a genuine gap in it is worth raising rather than routing around.
The method itself. How adoption works, how the loop runs, how the changelog is cut - that is the standard's own manual, adopted by reference and always read at latest. Copying it into your repo means running a fork of the method that nobody updates.
Decisions behind it
- ADR-023 - the method is read at the source, never vendored. Copying it in was the obvious alternative and it produces as many divergent copies of the method as there are repos, each frozen at the day it was adopted.
- One home per kind of knowledge. The alternative is a
docs/folder that grows by accretion, where the same fact lives in three files and the newest one is not necessarily the true one.
What is inside
decision-records/- the ADR/BDR decision logdiscovery/- discovery dossiers - provenance-stamped extracts per topic, never normative (ADR-024)ideas/- pre-decision ideas - status-driven, graduate into records/specs on approval (ADR-010)journeys/- per-persona journey maps coupled to capabilitiesresearch/- anonymized research studies feeding personas, ideas and specsrunbooks/- operational runbooks + postmortems - agent-followable at 3 a.m.sprints/- work sprints - what a team committed to and by when; an intent is in the pool or in exactly one sprint (ADR-028)adoption-assessment.md- what Gate 2's eight-pass assessment found - maturity per pass, top risks, findings grouped by the owner role that must act; the evidence Gate 5's count is derived from (ADR-048)adoption-intake.md- what Step 0 measured and asked before any align work proceeded - the record that makes intake checkable, not just performed (ADR-042)analytics.md- event-taxonomy tracking plan templateARCHITECTURE.md- how it is built - the altitude names it (filled from this repo)conventions.md- canonical conventions block - merged into AGENTS.md at adoptionfacts.example.json- the shape of a declared fact, reference only - do not rename or copy its placeholder content into docs/facts.json; write docs/facts.json from scratch, in this shape, once this repo has its first fact worth declaring (R4)facts.json- the facts this repo restates: one home each, every restatement declaredpersonas.md- the persona roster the R10 gate checks specs against - without it the gate has nothing to holdPRINCIPLES.md- the altitude apex R1 names - optional but expectedPRODUCT.md- what it is and where it is going (filled from this repo)README.md- the docs hub table