Taxonomy - where each kind of knowledge lands

The one map for "I have something to write down - where does it go?" It ends the recurring "is this an ADR or just a rule?" question. Boring and decisive on purpose.

You have this case - say this

You do not want to read a map. You want the thing filed. Say what you have and let the agent place it:

where does this go: we decided to stop supporting IE11
where does this go: guests should see the cancellation fee before confirming
where does this go: never call the payment API from the scheduler

Three sentences, three homes - a decision record, a spec, a convention. The agent answers with the destination and writes it there; if it is wrong, correcting the destination is one line, and cheaper than filing it nowhere.

Corner case - it is two things at once. "We decided guests see the fee" is a decision and a behavior. Both land: the record holds why the fork went that way, the spec holds what the product does. Neither restates the other.

Corner case - it might not belong in the repo at all. Meeting notes and raw material go to docs/discovery/, not into a spec. A spec that quotes a meeting has already started rotting.

The map

The two rules that end the oscillation

1. A significant decision produces BOTH - an ADR (the why + the rejected forms, so it is not re-litigated) AND a rule (the what to do now, in the methodology doc). Complementary, not either/or. E.g. "specs by capability" is ADR-002 and a rule in specs/README.
2. The ADR test is not "was there an alternative" - it is "is this a live, contestable trade-off that gets re-litigated?"
   • A clearly-wrong alternative, settled -> just a rule (one-line why inline).
   • A contestable trade-off, or one that keeps coming back -> an ADR too. Signal it needs an ADR: it already came back once (e.g. Spec Kit's NNN- numbering re-appearing as specs/cms/001-core/).

Right-size

Match the artifact to the substance. Do not reach for an ADR - or a new file, or a version bump - when a rule, a doc line, or a blog note fits. Boring and proportionate beats clever.

ADR vs BDR

• ADR - a technical decision, read broadly: framework, library, tooling, infra, data-model, distribution / structure. Architecturally significant, not enterprise-architecture-only.
• BDR - a business / product decision; a separate stream (different stakeholders, altitude).
• Sub-scope goes in the record's Tags, never in the acronym. Full policy: decision-records/ (ADR-001).

Testing lands in four places you already have

Testing looks like it needs a document of its own. It does not, and writing one is how a repo ends up with a testing policy that quietly disagrees with its specs. Four homes, all already on the map above:

• How much, and where each tier runs - a decision, and one of the eight forks R7 forces you to record. Argue it once, in the open; the alternative is arguing it again in every pull request.
• What must be true - the capability spec's acceptance criteria. A test asserts behavior, and behavior is written in the spec. A second document listing what to test is a copy, and the copy is the one that rots.
• The mechanics - runner, file layout, fixtures, coverage thresholds: the stack layer. These are properties of the language, not of the method, which is why a Python repo and a Node repo answering them differently is correct rather than inconsistent.
• How to run them - one line under Commands in AGENTS.md. That is the entire contract for a person or an agent arriving cold.

No new gate goes with this, and none is needed. A test sitting next to the code it covers already matches that capability's glob in specs/capability-map.json, so the coupling guard sees it without being told. A gate that demanded a test file be touched would be a gate satisfied by touching a test file.

Ideas / discovery before a decision

Not everything worth writing down is a decision, a rule, or a behavior - some of it is a speculative idea that may never ship. That is first-class here, not a lesser draft: an idea is explored end-to-end - including its provisional technical and business shape - in one file under docs/ideas/, and it is worth keeping in the repo even while it is only a maybe.

The rule that keeps the decision log honest:

• Do not mint an ADR/BDR/spec for an un-approved idea. Proposed in a record means "a decision awaiting ratification", not "an idea we might pursue" - dressing speculation as a record implies a fork was taken when none was.
• Statuses drive it (ADR-010): idea -> exploring -> approved | parked | dropped. On approval the idea graduates into the ways-of-working flow (backlog intent -> behavioral spec -> buildable spec + ADR/BDR) and the idea doc flips to graduated with links. Until then the whole idea, technical shape included, lives in its idea doc - and parked/dropped docs stay as cheap memory of why not.
• An idea is not a dossier. The moment a topic is actively pursued and accumulating materials (meetings, mails) whose provenance matters, it is discovery, not an idea: it gets a dossier under docs/discovery/<topic>/ and can draft its spec early, gaps held as typed open markers. The full model - entries, the Last reconciled: stamp, precedence - is discovery.md (ADR-024).

Living documents - updated in place

Everything in the map above is living. A spec, ARCHITECTURE.md, PRODUCT.md, the personas, the rules - they change as the product changes, by editing the same file in place. The current version is the truth; git is the history. Do not append incremental versions, -v2 files, or "amendment" sections when an update will do. Two qualifications keep this honest:

• When the previous state matters, say so in the doc. If a change reverses something important, keep one line on what changed and why - only when the old state is information a future reader will need, not as ritual.
• Decision records live by status, not by rewriting. An accepted ADR/BDR that no longer holds is not edited into a different decision - it is superseded by a new record (status flip + link). Same living principle, record altitude: the log stays honest while the current set of accepted records describes the present.

Nothing here is set in concrete - but a living edit still travels the ways-of-working loop (impact -> reconcile -> spec and code in the same PR), which is what keeps "living" from meaning "drifting".

Every folder explains itself - the README convention

Each directory carries a README.md that answers three things, in this order (GitHub renders it right where the reader lands - that is why it is README.md and not another name):

1. What lives here - one or two sentences.
2. Contents - one line per file/subfolder: what it is, when to read it.
3. Why this shape, and how to use it - the recommendation and the reasoning: why the folder is organized this way, what belongs here vs elsewhere, how an agent or human should work with it.

Keep the README readable: when a why or how needs length - worked examples, a full walkthrough - it moves to its own doc (a guide next to the README, or a case study, where the repo keeps a collection) and the README links it. The same-PR coupling applies: a change that adds, removes, or repurposes a file updates the folder's README in that PR.

Naming rule: README.md describes a folder; catalog.md is reserved for a curated list of items of one kind (like the decision checklist) - the two are different genres and must not be mixed.

Read this page's markdown, or its source on GitHub.