Documentation And ADRs

Use this when a decision or workflow must survive beyond the current chat.

Project Fit Check

Before writing docs:

1. Read existing documentation structure: docs/, docs/adr/, README.md, AGENTS.md, CONTEXT.md, runbooks, and contributing docs.
2. Follow local naming, numbering, status, and index conventions.
3. Update existing docs before creating new ones when the topic already exists.
4. Do not create an ADR for trivial implementation details.
5. If there is no durable doc structure, suggest the smallest useful file.

When To Write

Write durable docs for:

• architecture choices with real alternatives
• public API or data contract changes
• deployment, migration, rollback, or incident procedures
• security, privacy, or compliance decisions
• repeated workflows that multiple agents or humans need
• domain vocabulary that affects tests, UI copy, or architecture

ADR Shape

# NNNN Decision Title

## Status

Accepted | Proposed | Superseded

## Context

## Decision

## Assumptions

Facts the decision depends on, each one checkable (a file, a config value, a
measurement, a newer ADR). Revisit when: the trigger that makes them worth
re-checking.

## Consequences

## Alternatives Considered

## Follow-ups

Writing Rules

• Before you follow, cite or build on an ADR, check its Assumptions against the current system: code, config, measurements, newer ADRs. An ADR whose assumptions no longer hold is followed or ignored by whoever reads it first, and nothing records which. If one fails, do not follow it silently and do not ignore it silently. Amend the ADR with a dated note, or write a new ADR that supersedes it (old one set to Superseded, linked both ways), in the same change. If that is out of your scope, record the stale ADR as a finding for the owner of its repository. A decision that lives only in an ADR nobody re-checks is a stale claim.
• Prefer short, specific docs over sweeping essays.
• Capture why, not every implementation detail.
• Link to code, issues, PRs, or configs instead of duplicating them.
• Name trade-offs plainly.
• Keep runbooks actionable with commands, prerequisites, rollback, and verification.
• Update indexes and agent docs when discoverability matters.
• When a decision lands, re-read the plan documents written before it and correct them in the same change. A plan records the state at the time and goes stale silently; nothing in the decision record shows which plan it just contradicted, so a superseded instruction survives and is followed later as if it were current.
• A claim is checked against the system before it is written. A statement about behavior names the file that implements it. A number carries the date and the command or query that produced it, or says it was reasoned and shows the input. A claim you cannot settle without running something you should not run is written as unverified, naming what would settle it. When you touch a document, re-check the claims about the paths your change touched, not only the lines you edit. Every false claim was true when written.
• Reading an artifact is not checking it. A code comment, a docstring or an older record that states a mechanism is not evidence - it is where a false claim hides best, because it reads exactly like a verified one. So: if you cannot name the command that would falsify the sentence, you have not checked it, you have read something. Run it - the grep for a retired symbol, the query behind a count, the conversion behind a schema claim - and say in the change which claims you ran what against. A reviewer aimed at named claims re-derives; an unaimed one reads.
• Where a document names parts of the system - directories, services, lifecycle stages - the half a machine can check gets a test: every path it names exists, every stage it names matches the declaration the running code reads. That turns pointer rot, which otherwise surfaces when a reader follows a moved link, into a red check for a few lines of test. What such a test cannot reach is the prose, which is the argument for keeping the prose short and the table long.
• A diagram is checked by rendering it, not by reading it. Diagram grammars reserve words that look like ordinary node ids - in Mermaid's flowchart call parses as a callback name and fails the whole graph, and end, class, click, style, graph and subgraph behave the same way - so a diagram that reads correctly in the diff can render as nothing at all. Check the grammar outside the repository, so it needs no diagram tooling of its own: install mermaid and jsdom in a scratch directory, put a JSDOM window on globalThis before importing mermaid, and call mermaid.parse() on each fenced block. Whether the result is readable is a separate question and needs a real browser - JSDOM has no CSSStyleSheet, so mermaid.render() throws on it, and a browser driver refuses a file: URL, so serve the scratch directory over localhost.
• A diagram renders differently in each viewer. Markdown previews lay Mermaid out with different engines, dagre in one and ELK in another, and an edge back to the start of a flow makes a cycle that engines can break differently: in one real lifecycle chart ELK moved the entry node from first to last, while dagre kept it first. Draw a return as an edge into its own node at the end ("next signal, same entry") rather than back to the entry, keep short loops inside one part of the flow as ordinary back edges, and render in both engines before calling the layout done. Do not reach for a <---|x| b to flip a back edge: it parses, but Mermaid draws it with no arrowhead at all, so the edge loses its direction - check the arrowheads in the rendered SVG, not only the node order.
• A document that has outgrown its purpose is deleted, not maintained. Length is a defect of its own: nobody re-reads what they cannot finish, and the part nobody reaches is where stale claims survive. Version control is the archive.

Red Flags

• doc repeats code or config verbatim
• decision has no alternatives or consequences
• an ADR was followed without checking its assumptions, or has none to check
• runbook has no verification or rollback
• a claim in a doc is not true of the code, or cannot be checked at all
• no command would falsify the sentence, so nothing ever will
• a document is kept because deleting it feels lossy, not because it is read
• a diagram was checked by reading it, so nobody knows whether it renders
• documentation is added only to make a small change look larger