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. Everything the suite knows about 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 — lives in docs/. 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.

If it's in the docs, it is the absolute truth — but "truth" is typed (§3), and the only way docs stay true is 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. docs/ is the shared read-only context all plugins read; each plugin still keeps its own store, but the project's state of truth is here. 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/ — requirements, owned by prd-builder.
• docs/deep-analysis/ — audit findings, owned by maestro.
• docs/superpowers/specs/ — 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

Keep docs LEAN:

• STATUS.md stays concise — a snapshot with links to detail, never a dumping ground.
• ADRs and incidents are atomic — one decision / one postmortem per file.
• Link to docs/prd/ and docs/deep-analysis/, never copy them.

A doc that is verbose, duplicated, or out of date 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
   

   The type is a short tag the curator interprets — what each 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 that an audit/review ran and how many findings remain open (its applied outcomes return later as decision breadcrumbs). This is a fast, append-only breadcrumb trail (not polished docs) — the raw material the curate step consolidates with full context.
2. Curate (async, with full context) — at session end (a Stop hook) or on scribe:sync, the doc-curator agent — which has the real diff, decisions, and errors — consolidates the capture log into accurate ADRs, incident postmortems, and an updated STATUS.md, following the obligation contract (§4).
3. Verify (the "absolute truth" guarantee) — the doc-verifier agent adversarially checks every doc claim against the typed truth model (§3) plus cross-doc staleness: doc-vs-code drift, superseded-but-unmarked ADRs, shipped roadmap items still in the roadmap, answered open-questions, and accepted ADRs the code now contradicts. The verifier references maestro's adversarial-verify standard — refute-first, fresh independent eyes, evidence over assertion, atomic checks, multi-vote — and adds the typed-truth-model checklist as its domain layer.

Enforcement is advisory + a verification gate, matching maestro's advisory-hook philosophy: drift is flagged loudly as a defect, but it does not hard-block work. The discipline is upheld by making the cost of skipping it visible, not by stopping the line.

Relationship to other processes

• maestro is the canonical home of adversarial verification; doc-verifier embodies its adversarial-verify standard and adds the typed-truth checklist. maestro is untouched.
• 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 verifying every claim against the code.