documentation-discipline

name

documentation-discipline

description

Use whenever you make or discover a decision, fix a non-trivial error, change architecture or what the system does, or defer something undecided — and before acting on any task. The canonical contract for how docs/ works: docs/ is the single source of truth (read it first, write it after), its truth is typed and verified, and stale docs are always a defect. Adopted by every plugin, command, and agent that reads or writes project state.

documentation-discipline — the docs/ single source of truth

docs/ is the living single source of truth (SSOT) for a project: what it is, how it's built, why it was built that way, what broke and how it was fixed, and where it's going. This skill is the contract every plugin, command, and agent adopts: read docs/ before you act, write it after, and treat anything stale as a defect. Truth is typed (§3) and docs stay true only through verification (§5), never trust in an async writer.

1. docs/ is the single source of truth — read-first rule

Before acting on ANY task, read:

1. docs/STATUS.md — what the system is and does right now, the current focus, health.
2. the relevant docs/architecture/ — the boundaries, data model, and interfaces your change touches (owned by the architect plugin).
3. the open docs/adr/ — accepted decisions of record that constrain your change.

You do not start work, plan, design, or decompose from memory or from the prompt alone. If docs/ does not exist yet, it is bootstrapped first (scribe:init), never improvised per-task.

2. The canonical docs/ layout

The full layout, the "when to write what" table, and the ingestion rules live in references/docs-layout.md. In brief:

Path	Holds	Owner
docs/README.md	Index + "this is the SSOT" statement + how to navigate	scribe
docs/STATUS.md	Current-state snapshot: components, what it does now, focus, health — concise, links to detail	scribe
docs/architecture/	System design: boundaries, data model, interfaces, seams + extraction triggers	architect
docs/adr/NNNN-title.md	One decision per file	scribe (any plugin appends)
docs/incidents/NNNN-title.md	One postmortem per file	scribe
docs/roadmap.md	Future/planned work + triggers	scribe
docs/open-questions.md	Undecided, each with an owner	scribe

docs/ is an umbrella that INGESTS and LINKS, never duplicates: docs/prd/ (owned by prd-builder), docs/deep-analysis/ (owned by maestro), docs/superpowers/specs/. Reference these by link from STATUS / architecture / ADRs. Never copy their content in.

3. The typed truth model (the heart)

"If it's in the docs it's the absolute truth" — but the kind of truth differs by content type, so the right check is applied per type. Stale is ALWAYS a defect, whatever the type.

Content	Lives in	Truth means	Verified by
System facts	STATUS.md, architecture/	matches the code	adversarial doc-vs-code reading; any drift = defect
Decisions	adr/	decision of record	currency (superseded ones marked) + consistency with code
Incidents	incidents/	accurate postmortem	anchored to the real fix in the code
Intent / future	roadmap.md, open-questions.md	current + owned + non-stale	shipped item → moved to STATUS; decided question → became an ADR

Two locked rules carry the most weight:

• System facts drift = defect. If STATUS.md or architecture/ says something the code no longer does, the doc is wrong and must be fixed. The code is the referent.
• An accepted ADR the code contradicts is FLAGGED for human resolution — neither auto-wins. The code may have violated the decision (a bug/regression), or the decision may be stale (the ADR should be superseded). A human decides which. The verifier surfaces the conflict; it does not silently rewrite the ADR or excuse the code.

Staleness is cross-document, not just per-doc: a shipped roadmap item must move to STATUS.md; a decided open-question must become an ADR; a superseded decision must be marked. Leaving these in place is a defect the verifier flags.

4. The obligation contract

Every plugin, command, skill, and agent adopts this. After doing work, the matching doc is updated as part of "done" — not optionally, not later:

You did this	You owe this doc
Made / changed a decision	New or updated ADR (docs/adr/), including a trigger to revisit
Fixed a non-trivial error	Incident (docs/incidents/): symptom, root cause + WHY, where/how fixed, why that fix, prevention
Changed the architecture	docs/architecture/ update and an ADR for the decision
Changed what the system is / does	STATUS.md
Deferred / left something undecided	open-questions.md (with an owner) — or roadmap.md if it's planned

Which rows a change owes is detected hook-side, not felt: the docs_update_gate hook computes the owed rows from countable git-diff + capture-log patterns and prints only those rows (the owed-list). The one obligation no pattern can catch stays yours: capture (§5.1).

Keep docs LEAN: STATUS.md stays a concise snapshot with links; ADRs and incidents are atomic (one per file); link to docs/prd/ and docs/deep-analysis/, never copy them. A verbose, duplicated, or out-of-date doc is a defect just as much as a missing one.

5. Capture → curate → verify

Trust comes from VERIFICATION, not from trusting an async writer. Three tiers, so docs never block work yet never drift:

1. Capture (sync, cheap) — the moment you make a decision, hit a non-trivial error, or fix one while working, append a one-line breadcrumb to docs/.scribe/capture.log — do not wait for the curate step. A decision or error is semantic (only the working agent knows it happened), so capture is an obligation of every agent that adopts this skill, not something a hook can do for you. Append it with:

   mkdir -p docs/.scribe
   echo "$(date -Iseconds) | <decision|error|fix|assumption|review> | <one line: what + why>" >> docs/.scribe/capture.log
   

   What each type becomes: decision → an ADR (and STATUS.md if it shipped behavior); error/fix → an incident; assumption → an open-questions.md entry; review → a STATUS.md note (findings applied later return as decision breadcrumbs).
2. Curate (async, with full context) — on scribe:sync or at session end (a Stop hook nudge), the hook-computed owed-list is paid: the doc-curator agent is dispatched once per owed doc, with only that row's capture-log lines + diff hunks in context, and fills the matching template. The curator consumes the owed-list; it never re-derives what is owed.
3. Verify (the "absolute truth" guarantee) — the doc-verifier agent checks every doc claim against the typed truth model (§3) plus cross-doc staleness, refute-first: each claim type has a pre-written executable probe in references/verifier-probes.md (the canonical probe library), evidence is the probe's captured output, and high-stakes claims are checked by N independent votes per that file's tier table (strict majority; one evidenced dissent vetoes an accurate).

Enforcement is advisory: drift is flagged loudly as a defect, but it does not hard-block work. The cost of skipping the discipline is made visible, not enforced by stopping the line.

Relationship to other processes

• architect owns docs/architecture/ and writes ADRs through this contract.
• prd-builder owns docs/prd/; maestro owns docs/deep-analysis/; both are ingested by link, never copied.
• scribe:init bootstraps docs/ (brownfield: via a maestro deep-analysis pass, so the baseline is reverse-engineered from real code and therefore verifiable = true).

The mantra

docs/ is the single source of truth: read it before you act, write it after, and a stale doc is a defect — caught not by trusting the writer, but by probing every claim against the code.