Doc Diagnostic

doc-diagnostic

The diagnostic and canon skill. Owns three things:

1. The alternatives catalog -- what to write when a user impulse should not be an ADR. Full catalog: references/alternatives-catalog.md. 2. The ADR canon -- templates, status lifecycle, numbering, required fields, immutability rules. (In this file.) 3. The audit procedure -- folder-level KEEP / MERGE / REWRITE / DELETE / MOVE / BACKFILL-ADR classification used by /doc-audit. Full procedure: references/audit-procedure.md.

Use this skill when routing a doc request, picking a template, naming a status, or auditing an existing doc set. The drafting / discovery / critique skills consume the canon defined here; they do not redefine it.

The four-question diagnostic (run before recommending any doc)

The canonical four-question check. The doc-expert agent and every other skill in this plugin reference this section rather than restate it. Before agreeing to produce any document, run all four. If any answer is "no" or "unclear," the doc should not be written yet.

1. Purpose -- one sentence stating what question this doc answers for a reader who already knows the system exists. 2. Audience -- a specific reader in a specific situation. ("Future maintainers" is not an audience; "an on-call engineer at 03:00 with a P1" is.) 3. Owner -- a named human accountable for keeping it true. No owner → drift within months. 4. Update trigger -- a concrete event that causes the doc to be revisited or superseded. No trigger → fossil-in-waiting.

If all four are answerable, proceed to the "is this an ADR?" diagnostic in the doc-expert agent body.

Architecturally Significant Requirement (ASR) -- canonical definition

An ADR captures a single architectural decision and its rationale. An architectural decision addresses a requirement that is architecturally significant -- an ASR with "a measurable effect on the architecture and quality of a software and/or hardware system." If the change is not architecturally significant, an ADR is the wrong tool -- route via the alternatives catalog.

Beyond architecture -- "decision records" more broadly

The same form generalizes to product, business, policy, security-program, and process decisions -- anywhere a justified, hard-to-reverse choice deserves a rationale that outlives its authors. Convention: rename docs/adr/ to docs/decisions/ and relax the ASR test to "is this decision worth recording at all?" Templates, lifecycle, numbering, immutability, and Relationships-mirror rules hold unchanged. Umbrella: github.com/joelparkerhenderson/architecture-decision-record; see also references/adr-template-catalog.md.

The alternatives catalog (when NOT to write an ADR)

When the diagnostic says "not an ADR," route via references/alternatives-catalog.md -- it maps every common impulse to the correct doc form, explains why an ADR would be wrong, and names the Diátaxis four (tutorial / how-to / reference / explanation). ADRs are not Diátaxis explanations. Load it whenever the user debates "ADR vs RFC vs design doc vs runbook vs how-to" or asks "where should I document X?"

ADR canon

Template selection

Pick the smallest template that captures the decision honestly:

Pick once per project; do not mix templates within a single log unless explicitly migrating.

Canonical status lifecycle

  proposed  ----accepted---->  accepted  ----changed---->  superseded
                                      |
                                      +--no-longer-applies-->  deprecated

Explorer-compatible status values are lowercase proposed, accepted, deprecated, superseded. Do not overload status with rfc, rejected, backfilled, or explanatory strings.

• proposed -- under discussion, including ADRs serving as RFCs (add rfc-deadline, do not invent status: rfc).
• accepted -- in force.
• superseded -- replaced by a later ADR; the new ADR's supersedes list creates the edge.
• deprecated -- no longer applies but no new decision replaces it, or a proposal rejected but kept for its "why not." Explain in body, not status.

Immutability and supersession

The cardinal rule: "Don't alter existing information in an ADR." Amend or supersede.

• Once Accepted, the body is append-only: typo fixes, a superseded by note, dated entries under an "Amendments" heading.
• A changed decision is a new ADR naming the old one in supersedes. The old ADR may get a superseded by: NNNN reader note but otherwise stays untouched. The new ADR's supersedes list is the edge; superseded-by body prose is not.
• Teams preferring "living document" with dated inline amendments must state it up front in the log's README.md.

Numbering, naming, ownership

• Numbering: monotonically increasing, zero-padded (0001, 0002, ...). Never reuse. The number IS the identity.
• Filename: zero-padded id + present-tense imperative phrase, lowercase, hyphenated, .md (0007-use-postgres-for-primary-store.md).
• Ownership: deciders as a YAML array (accountable); optionally consulted / informed (MADR RACI). "The team" is not an owner.
• Date: ISO 8601. Stamp at acceptance, not first draft.
• Review cadence: a concrete trigger on the ADR ("Revisit when we exceed 10k QPS"), not "revisit annually."

Required fields

Every ADR contains:

1. Title -- NNNN. Decision (imperative verb phrase). 2. YAML frontmatter -- mandatory. A --- block with at minimum title, status, date, deciders. Add supersedes / amends / relates-to when relationships exist. Optional: tags, review-by, expires, confidence: high|medium|low, confidence-score, rfc-deadline (when status: proposed acts as an RFC). Gray-matter parsers read only the frontmatter; missing it orphans the node. 3. Body Relationships mirror -- mandatory whenever frontmatter relationships exist. MADR 4.0.0 ## More Information → ### Relationships, link-prefix vocabulary (Supersedes, Superseded by, Amends, Amended by, Related to). Body-scanning parsers read only this section; the two surfaces must agree. 4. Context -- the architecturally significant forces; a stranger three years later understands why this had to be decided now. 5. Decision -- the choice, present tense, standing alone. 6. Decision drivers (MADR) or implicit in Context (Nygard). 7. Alternatives considered -- realistic ones at the same level of abstraction, each with a one-paragraph "why not." Skip pseudo-alternatives. 8. Consequences -- Good, because... and Bad, because... plus follow-up work. 9. Confirmation / Validation (MADR full) -- how compliance is enforced. 10. Re-evaluation triggers -- concrete conditions that should cause a new ADR to supersede this one.

Storage and discoverability

• Keep ADRs in the source repository, in source control, alongside the code they govern.
• Explorer-friendly locations: docs/adr/, docs/decisions/, docs/architecture/decisions/, **/adr/*.md. Pick one; document it in the log's README.md.
• Provide an index in that README.md listing every ADR with status and a one-line summary. The index is navigation, not the graph; index-hub links are not edge signals.
• Default to MADR 4.0.0 + frontmatter + body Relationships mirror. Frontmatter supersedes / amends / relates-to feed gray-matter parsers; body ### Relationships feeds body-scanning parsers; either alone half-renders. If the project already uses Nygard, Y-statement, arc42, or Tyree-Akerman, follow it. MADR: adr.github.io/madr/, source github.com/adr/madr.
• Body lines like Related ADRs: outside ### Relationships, or Related docs: in ### Notes, are courtesy navigation -- not edges.
• ID format in frontmatter lists: zero-padded four-digit strings ("0008"). Explorer parsers extract digits with /(\d+)/ and zero-pad, so 8, "08", "0008", "ADR-0008" resolve identically -- but zero-padded strings render and sort predictably.
• Cross-link from code when feasible (// See docs/adr/0007-use-postgres-for-primary-store.md).
• State the governance rule for relationship-link maintenance: if Accepted ADRs are immutable, either allow metadata-only relationship-list edits + body Relationships additions, or require a named exception.
• Offline canon check: plugins/doc-master/scripts/validate_adrs.py. See plugins/doc-master/scripts/README.md for the full per-file check list and CLI flags. Use during /doc-audit or as a CI gate, not as a substitute for the four-question check.

Canonical mirror example

---
title: "Use Postgres for primary store"
status: accepted
date: 2026-05-20
deciders: [Jane Doe]
supersedes: ["0004"]
relates-to:
  - id: "0011"
    reason: "shares the tenancy model decided in 0011"
---

# 0017. Use Postgres for primary store

## More Information

### Relationships

- Supersedes [ADR-0004](0004-use-dynamodb-for-primary-store.md) -- replaced because Q3 reporting needs sub-200ms joins.
- Related to [ADR-0011](0011-tenancy.md) -- shares the tenancy model decided in 0011.

Both surfaces must agree. Stray Related ADRs: lines in ### Notes, index-hub entries, or superseded-by body notes are courtesy navigation, not edges.

Repo-level cornerstones around the decision log

A decision log sits inside a broader set of community-health files: README, LICENSE, CONTRIBUTING, CODE_OF_CONDUCT (opensource.guide four-file canon), plus the extended GitHub profile (SECURITY, SUPPORT, CODEOWNERS, FUNDING, CITATION, .github/ templates). doc-master does not auto-create any of these; the four-question diagnostic still applies. Full canon in the repo-health skill -- load it when the user sets up community-health files, audits repo bootstrap docs, or picks a license / code-of-conduct / contribution guide.

ADR failure modes

The eleven canonical failure modes (drift, ADR-PRD duplication, bundled decisions, premature ADR, template thrash, decision-by-AI-without-buy-in, and the rest) with symptoms and remedies: references/failure-modes.md. Load during audits and adr-critique.

Folder-level audit procedure (used by /doc-audit)

Follow the eight-step procedure in references/audit-procedure.md: Inventory → ADR-canon test → four-question test → drift → duplication → misclassification → backfill-candidate detection (ASR test against shipped-change evidence) → numbered KEEP / MERGE / REWRITE / DELETE / MOVE / BACKFILL-ADR action list.

BACKFILL-ADR is a candidate, not a draft -- the audit surfaces it; the architect decides whether to load adr-backfill. Evidence must appear in two independent locations; reconstruction-confidence: low routes to open-questions.md. The procedure file pins the hard constraints (no body edits on Accepted ADRs, no bulk renumbering, no auto-generated Owners, no deletion without sign-off) and the post-approval flow.

Anti-padding rule

Every doc recommended must answer all four diagnostic questions (Purpose, Audience, Owner, Update trigger). If one is unanswerable, the doc should not exist yet. This applies to ADRs, RFCs, how-tos, references, explanations, tutorials, runbooks, READMEs, and CONTRIBUTING alike. Documentation is a cost as well as a benefit -- the right number is the smallest number that keeps the system understandable, operable, and decisive.

References

• references/alternatives-catalog.md -- Diátaxis / RFC / runbook routing
• references/failure-modes.md -- eleven ADR failure modes with remedies
• references/audit-procedure.md -- folder-level audit procedure with hard constraints
• references/changelog-canon.md -- Keep a Changelog 1.1 + SemVer 2.0.0
• references/runbook-canon.md -- runbook structure for paged incidents (not how-to)
• references/postmortem-canon.md -- blameless postmortem (PagerDuty + Google SRE)
• references/open-questions-canon.md -- standalone open-questions register
• references/agentic-docs-canon.md -- AGENTS.md convention for AI-agent context
• references/adr-template-catalog.md -- template index (Nygard / MADR short / MADR long / Y-statement / Tyree-Akerman / arc42 §9)
• ../_shared/adr-is-not.md -- canonical "ADR is NOT" checklist
• adr-discovery, adr-drafting, adr-critique skills
• c4-model skill -- canonical-C4 LikeC4 diagrams
• repo-health skill -- community-health files (README / LICENSE / CONTRIBUTING / CODE_OF_CONDUCT / SECURITY / SUPPORT / templates / REUSE-SPDX)

ADR template catalog — the canonical index

The master index of ADR template forms doc-master knows and can route between. Load this when the user asks "which ADR template should I use?", "what's a Y-statement?", "Nygard vs MADR vs Y-statement vs arc42 vs Tyree-Akerman", or "is there a one-paragraph ADR form?"

The authoritative catalog of community-curated ADR templates lives at [adr.github.io](https://adr.github.io/) — when in doubt about a template not listed here, route there first.

The forms doc-master knows

doc-master's default is MADR (currently 4.0.0) with YAML frontmatter and a body Relationships mirror; see ../SKILL.md "Storage and discoverability" and ../../adr-drafting/references/template-fields.md for the full canonical fields.

Y-statement template (inline)

A Y-statement compresses an ADR into a single paragraph. The form is fixed:

In the context of <use case / functional requirement>, facing <concern / non-functional requirement>, we decided for <chosen option> and neglected <other options>, to achieve <quality goal / criteria>, accepting <downside / consequence>, because <additional rationale>.

Each slot is mandatory. A Y-statement missing any slot is a marketing sentence, not a decision record.

Example:

In the context of the customer-facing API, facing sub-200ms p95 latency requirements, we decided for Postgres with read replicas and neglected DynamoDB, to achieve sub-150ms reporting-query latency with multi-table joins, accepting the operational overhead of self-managing replication, because the reporting workload requires SQL joins and the team has stronger Postgres operational experience than DynamoDB experience.

Y-statements are excellent as:

• The opening summary atop a longer ADR (give readers the gist before they commit to the full doc).
• Index-row summaries in the decision log's README.md.
• Executive-summary versions of an existing ADR for stakeholders.
• RFC pitch lines that compress the proposal into a single sentence.

They are insufficient when:

• The decision genuinely needs side-by-side comparison of multiple alternatives on multiple criteria.
• The Consequences need bullet lists with Good-because / Bad-because framing.
• Traceability requires structured fields (decision drivers, confirmation, re-evaluation triggers).

Source: Olaf Zimmermann's original Y-statement post on Medium, medium.com/olzzio/y-statements-10eb07b5a177. Route via adr.github.io for the up-to-date catalog entry.

Selection rules

1. If the project already uses a template — use it. Consistency outweighs minimalism. Switching templates mid-log is template thrash (a named failure mode); do not propose it lightly. 2. If the project is starting fresh — default to MADR 4.0. It has the best balance of structure, parser support, and community tooling. 3. If the team is small and the decision is simple — Nygard or MADR short. Do not pad three-field decisions with empty MADR-long sections. 4. If you need a one-paragraph summary — Y-statement atop a longer ADR. The longer ADR remains the canonical record. 5. If the project already uses arc42 or Tyree-Akerman — keep it. Translating into MADR for cosmetic reasons is template thrash.

When NOT to use any of these — beyond architecture

If the user is recording non-architectural decisions (product decisions, business decisions, policy decisions) and finds the "architectural" framing constraining: the broader pattern is just decision records, and the directory is conventionally renamed to decisions/. See ../SKILL.md "Storage and discoverability" — the Joel Parker Henderson reference repo at github.com/joelparkerhenderson/architecture-decision-record catalogs the broader pattern.

The shape is the same; only the ASR test loosens. The four-question diagnostic still applies.

AGENTS.md canon — AI-agent context file

The canonical reference for AGENTS.md. Load this when the user asks "where do I tell our AI agents about this repo?", "should I write an ADR for 'we use Claude Code'?", "we have CLAUDE.md and .cursorrules — what should we use instead?", or "what's the convention for agent instructions?"

AGENTS.md is a vendor-neutral, agent-readable file that describes a codebase to AI coding assistants: conventions, build commands, test commands, code style, deployment notes — anything an agent needs to operate effectively in the repo. It is the converged community answer to the proliferation of vendor-specific files (CLAUDE.md, .cursorrules, .github/copilot-instructions.md, .continuerc, and the rest).

Upstream: agents.md. The convention is now stewarded by the Agentic AI Foundation as a vendor-neutral spec.

The closest-AGENTS.md-wins rule

For monorepos and nested projects:

• The agent reads the nearest AGENTS.md walking upward from the working directory.
• Sub-project AGENTS.md files override parent files for their own scope, on a per-section basis where the agent supports it.
• Repo root AGENTS.md provides the defaults; subdirectory files refine them for their specific package / service / language.

This means a monorepo with packages/frontend/AGENTS.md and packages/backend/AGENTS.md can give the agent fundamentally different instructions per package (npm vs gradle, prettier vs spotless, etc.) without conflict.

Migration from vendor-specific files

If the repo currently has vendor-specific agent-context files, migrate them:

Symlinks during migration are the safe path. They preserve compatibility with tools that look for the vendor-specific name while making AGENTS.md authoritative. On Windows, where symlinks need elevated permissions or developer mode, the alternative is a tiny pointer file (e.g., a CLAUDE.md containing only "See AGENTS.md.") with the same effect.

What goes in AGENTS.md

A typical AGENTS.md covers:

• Build, test, and lint commands — the exact commands the agent should run, with no guessing.
• Code style — language version, linter / formatter config, naming conventions that the linter does not cover.
• Repository layout — where source, tests, docs, configs live.
• Dependency rules — what is allowed, what requires an ADR, vendor-pinning policy.
• Branching / PR conventions — branch naming, commit message style (Conventional Commits etc.), required reviewers.
• Forbidden actions — what the agent must not do (force-push, edit specific protected files, commit secrets, bypass CI).
• Pointers to other docs — ADR directory, runbook directory, security policy, contribution guide.

It does not typically duplicate ADRs, runbooks, or the README — it points to them.

"Should I write an ADR for 'we use Claude Code'?" — no

Picking an AI coding assistant is not an architectural decision in the ASR sense:

• It is reversible — switch to a different agent tomorrow.
• It has no measurable effect on system architecture or quality.
• It does not constrain future architectural choices.

The choice of agent is a tooling preference, like the choice of editor or terminal. It belongs in AGENTS.md (the configuration / instruction file the agent reads) or in CONTRIBUTING.md (if there are project-wide expectations about how agents are used). It does not belong in the decision log.

What may be an ADR-worthy decision in the same neighborhood:

• "All AI-generated code requires human-named reviewer sign-off before merge" — governance, often architecturally significant.
• "We forbid AI agents from modifying files under /security/" — constraint with measurable effect on review surface and compliance.
• "We license-screen all AI-suggested dependencies through workflow X" — a process commitment with measurable impact.

These produce an ADR because the policy has architectural and compliance implications. The choice of which agent is configuration.

Common failure modes

Routing — when this is not the answer

• A decision about how the team uses agents with architectural / compliance impact → ADR.
• A decision about which agent to use → AGENTS.md (tooling preference, not a decision).
• A general "what conventions does this repo follow" doc for humans → CONTRIBUTING.md. AGENTS.md may link to it.
• Per-language style → linter / formatter config. AGENTS.md points at the config; it does not restate it.
• Forbidden-actions policy with legal / security weight → may be both an AGENTS.md entry and a SECURITY.md section, depending on audience.

Alternatives catalog — when NOT to write an ADR

When the four-question diagnostic and the ASR check say "not an ADR," route the user to the right home. Each row below maps a common user impulse to its correct documentation form and the reason an ADR would be wrong.

This catalog is the routing reference for doc-diagnostic. Load it whenever the user is debating "ADR vs RFC vs design doc vs runbook vs how-to" or asks "where should I document X?"

The catalog

The Diátaxis four

The most-confused alternatives. Name them precisely:

• Tutorial — learning-oriented; a guided lesson; serves a learner. "Build your first API endpoint."
• How-to guide — task-oriented; sequence of steps; serves a competent user with a goal. "How to deploy to production."
• Reference — information-oriented; austere, neutral, product-led description. "Configuration options."
• Explanation — understanding-oriented; discursive, considers alternatives, gives the why. "About the request-routing model."

ADRs are not Diátaxis explanations. An explanation answers "can you tell me about X?" and reflects on the bigger picture. An ADR answers "what did we decide, and why this rather than the alternatives, and what does that commit us to?" An explanation may link to ADRs to surface the rationale; it should not duplicate them.

How to use this catalog

1. Run the four-question diagnostic in SKILL.md first. 2. If the request fails the diagnostic, find the closest row above by matching the user's words. 3. Name the alternative explicitly, give the path, then re-run the four-question check on the alternative. 4. If no row fits, fall back to the Diátaxis four: ask whether the user needs learning, task completion, reference lookup, or understanding.

Folder-level audit procedure (used by /doc-audit)

The canonical procedure for auditing an existing doc set. The /doc-audit command hands the audit to the doc-expert agent, which loads doc-diagnostic and follows this procedure.

This reference is the long-form spec. The short pointer in SKILL.md and the user-facing description in commands/doc-audit.md both route here.

Inputs

• Target directory — default docs/. The user may scope to a subdirectory (e.g., docs/adr/) or expand to additional paths (e.g., architecture/ plus root-level *.md).
• Optional context — which ADRs the user already suspects of drift; the project's stance on immutability vs living-document ADRs; files to exclude (generated docs, third-party imports, license boilerplate).

The procedure

1. Inventory. Glob the target directories. Count files, group by type:

• ADR (under adr/, decisions/, or with ADR-shaped filenames)
• RFC (under rfcs/ or with explicit "Status: Open / Closed" headers)
• Runbook (under runbooks/ or with operational/incident framing)
• Diátaxis: how-to, reference, explanation, tutorial
• README / index files
• Loose markdown that doesn't fit any of the above

2. Test each ADR against the canon. For every ADR check:

• Status set to an ADR Explorer-compatible value (proposed, accepted, superseded, deprecated) with no overloaded rfc, rejected, or backfill text?
• Owners / Deciders named as a YAML array (humans, not "the team")?
• Relationship fields shaped for graphing: supersedes and amends as YAML lists, relates-to as {id, reason} objects?
• Confidence is high, medium, or low (with optional separate confidence-score if numeric scoring is used)?
• Alternatives considered, at the same level of abstraction?
• Consequences listed — both Good and Bad?
• Re-evaluation triggers present and concrete (not "annually")? Optional expires used only when expiry is real?
• Supersession graph edge present on the new ADR's supersedes list? Do not rely on superseded-by / superseded by alone.
• Numbering monotonic? Filename starts with the numeric id and uses an imperative verb phrase?
• ADRs live under ADR Explorer-friendly roots (docs/adr/, docs/decisions/, docs/architecture/decisions/, **/adr/*.md), or architecture/decisions/ is documented as needing custom root configuration?
• Each failure points to a row in references/failure-modes.md.

3. Test each non-ADR against the four questions. Purpose / Audience / Owner / Update trigger (see SKILL.md "The four-question diagnostic"). Files that fail two or more should be flagged for deletion or rewrite.

4. Detect drift. Cross-reference ADR claims with the code. If the ADR says "we use Postgres" and the codebase has switched to SQLite, flag it. Drift is the most common failure mode in long-lived doc sets.

5. Detect duplication. Two docs that answer the same question should be merged; the duplicate becomes a redirect to the canonical.

6. Detect misclassification. A "decision" doc that's actually a how-to should be moved. A "runbook" that's actually an explanation should be moved. Cite the Diátaxis quadrant for each move (see references/alternatives-catalog.md).

7. Detect backfill candidates — run the ASR test against shipped-change evidence.

• Surface to walk. Commit history, migration files, dependency manifests, infra files, removed dependencies, removed subsystems, retired modules, retired vendors, policy unifications, and subsystem retirements. For each, ask: did the team make an architecturally significant decision that was never recorded?
• ASR test. Apply the same measurable-effect-on-architecture-or-quality test used during pre-flight discovery. No measurable signal, no row.
• Two-locator rule (false-positive guard). Evidence must appear in at least two independent locations before a backfill row is emitted. A single commit message alone is not enough. A commit plus a deleted module, or a migration plus a removed dependency in the manifest, is enough.
• No measurable signal? Do not emit a row. Log it in open-questions.md instead, naming what evidence would have to surface to upgrade it.

8. Report. Produce a numbered list of recommended actions:

• KEEP — passes the canon and the four-question test as-is.
• MERGE — overlaps with another doc; specify the merge target.
• REWRITE — content is salvageable but violates the canon or fails the four-question test.
• DELETE — fails the four-question test with no salvage path. Requires human approval.
• MOVE — wrong location for its content type. Specify the new path and the Diátaxis quadrant.
• BACKFILL-ADR — shipped-change evidence reveals a past architectural decision that was never recorded. Surface as a candidate, not a draft. Use the row schema below.

Each entry gets a one-sentence rationale. Do not bulk-delete without human approval.

BACKFILL-ADR row schema

Each BACKFILL-ADR row has exactly five fields:

Backfill confidence rule

If reconstruction-confidence is low, do not emit a BACKFILL-ADR row. The decision is not reconstructible to a standard that would justify a record in the decision log. Emit an open-questions.md row instead, naming what evidence would have to surface to upgrade the confidence to medium or high. Surfacing the gap is more honest than fabricating a rationale at backfill time.

Hard constraints

• Never delete or move a file without explicit human sign-off on the action list.
• Never edit an Accepted ADR's body. Header-only metadata or human-readable supersession notes require sign-off; ADR Explorer graph edges belong in the new ADR's supersedes list. Body changes require a superseding ADR drafted via adr-drafting.
• Never bulk-renumber ADRs. Numbers reflect creation order; gaps and out-of-order acceptance are fine.
• Never auto-generate Owners or re-evaluation triggers for ADRs that lack them — those need human input. Flag them in the action list as REWRITE — needs Owner / re-evaluation trigger input.

Execution after approval

After the user approves the action list, execute the actions one file at a time, summarizing each change so the user can stop the audit at any point. Batch execution is allowed only when the user explicitly approves a group of actions ("apply all MOVEs," "apply all DELETEs").

Changelog canon — Keep a Changelog 1.1 + SemVer 2.0

The canonical reference for the CHANGELOG.md file. Load this when the user asks "where do I document this user-visible change?", "do we need a changelog?", or "what version should we bump to?"

A changelog is for humans, not machines. It records what changed in each release, grouped by intent, in reverse-chronological order. It is not a commit log, not a release-notes blog post, and not a marketing summary.

Upstream specs:

• keepachangelog.com/en/1.1.0 — Keep a Changelog 1.1 (the file format).
• semver.org/spec/v2.0.0.html — Semantic Versioning 2.0.0 (the version-number contract that the changelog reports against).

File location and shape

• Single file, at the repo root: CHANGELOG.md.
• Reverse-chronological — the newest release appears at the top, immediately below the ## [Unreleased] block.
• An ## [Unreleased] section is always present at the top, even when empty. It accumulates entries between releases; on release, it is renamed to the version being shipped and a fresh empty ## [Unreleased] is created above it.
• Every released version block carries an ISO 8601 date in the heading: ## [1.4.0] - 2026-05-21.
• Released sections are never edited — fix mistakes by adding a follow-up entry in the next release, not by rewriting history.

The six categories — and only six

Keep a Changelog defines exactly six entry categories. Do not invent new ones, do not split them, do not rename them.

If an entry does not fit one of these six, it is probably not a changelog entry — it is internal refactoring, a tooling change, or a developer-process note, none of which belong here.

SemVer cross-reference

The category an entry lands in determines the version bump:

The rule of thumb: MAJOR for breaking, MINOR for new, PATCH for fixes. When in doubt, ask "does an existing caller need to change anything?" If yes, MAJOR. If they can just upgrade, MINOR or PATCH.

Canonical example

# Changelog

All notable changes to this project are documented in this file.

The format is based on [Keep a Changelog 1.1](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Added
- Retry budget on the queue consumer.

## [1.4.0] - 2026-05-21

### Added
- `--dry-run` flag on the migrate command.

### Changed
- Logging now emits structured JSON by default.

### Deprecated
- The `--legacy-output` flag. Removal scheduled for 2.0.0.

### Fixed
- Race condition in the cache warmer (#412).

## [1.3.1] - 2026-04-30

### Security
- Upgraded dependency X to address GHSA-xxxx-yyyy-zzzz.

Common failure modes

Routing — when this is not the answer

• A user-visible API change that requires migration steps → changelog entry + a separate migration guide (Diátaxis how-to). The changelog says what changed; the migration guide says how to adapt.
• An internal refactor that doesn't affect users → commit message + PR description, not the changelog.
• A security advisory with embargo / coordinated-disclosure framing → `SECURITY.md` advisory + a Security entry referencing the advisory ID.
• A choice between two implementation options that was decided during the release cycle → ADR, not a changelog entry. The changelog reports the outcome; the ADR records the rationale.

ADR failure modes and concrete remedies

The eleven canonical ADR failure modes. Load this reference during folder-level audits (/doc-audit) and during adr-critique to put a name to what's wrong with a given ADR.

Each row pairs a symptom with the remedy. Most failure modes have an obvious fix; the cardinal rule (SKILL.md "Immutability and supersession") still applies — never silently edit an Accepted ADR.

How to use this table during an audit

For each ADR in scope:

1. Read header (Status, Owners, Supersedes / Superseded by, Date). 2. Read body (Context, Decision, Alternatives, Consequences, Re-evaluation triggers). 3. Match symptoms against the rows above. One ADR can hit multiple failure modes. 4. Record the failure-mode name alongside the audit verdict (KEEP / MERGE / REWRITE / DELETE / MOVE). Naming the failure mode is faster than re-deriving the problem from scratch.

How to use this table during line-by-line critique

The adr-critique skill walks an ADR line by line. When a line trips a rule (marketing language, hedging, missing-why, future-proofing essay, passive-voice corporate text, implementation bleed), check whether the surrounding section also exhibits one of the failure modes above — they often co-occur. A "missing context" ADR is usually also full of hedging because the author had no constraint to argue from.

Open-questions register canon

The canonical reference for an open-questions register as a standalone documentation form. Load this when the user says "we're not ready to decide yet," "park this for later," "what should I do with the things we don't know?", or "where do unresolved architectural questions go?"

An open-questions register is a scoped, owned, dated list of unknowns that block or qualify future decisions. It is the legitimate alternative to a premature ADR — when a team feels pressure to "write something down" before the decision is actually made, the register is where that pressure should land.

Why this is not an ADR

An ADR captures a made decision and its rationale. An open question by definition has neither — it has a question and (at best) candidate answers awaiting evidence. Putting open questions in the ADR log:

• Pollutes the decision graph with non-decisions.
• Creates ADRs that sit in status: proposed for months.
• Mixes "what did we decide" with "what are we still figuring out," which confuses every reader.

The register keeps unknowns visible without converting them into decisions they are not.

File location

• Single file, in the architecture area but outside the ADR directory the parsers walk:
• Default: docs/architecture/open-questions.md.
• Alternative: docs/decisions/open-questions.md if the project uses docs/decisions/ for ADRs — keep the file at the parent of the ADR directory, not inside it.
• One register per system / product area. Do not maintain one register per team — too many registers means none of them are read.

The register is intentionally one level up from the ADR globs so ADR Explorer / ADR Manager / validate_adrs.py do not try to parse it as an ADR.

Distinction from adr-discovery's open-questions-register.md

doc-master has two related artifacts:

The discovery file is a focused subset; this canon is the long-lived home. Discovery questions that survive past their ADR (because the team chose to ship the ADR with the question PARKED) graduate into the standalone register here.

Required columns per row

Each row of the register answers six questions. Missing any one of these and the row is too vague to act on.

Optional columns:

• Raised — ISO 8601 date the question was added.
• Related ADRs — IDs of ADRs this question relates to (e.g., it qualifies an existing ADR, or will produce a new one).
• Status — OPEN, ANSWERED, PARKED (matches the discovery file's vocabulary).

Graduation rule

When the Measurement plan produces evidence, the row graduates — it does not stay open forever.

• If the resolved question is architecturally significant (an ASR — passes the ASR test in SKILL.md): promote to an ADR. The register row gets marked ANSWERED with the date and a link to the new ADR.
• If the question turned out to not be architecturally significant (a coding convention, a settled-elsewhere policy, a reversible UX detail): close the row and route the answer to the correct alternative form via alternatives-catalog.md.
• If the team decides to ship with the question unresolved: mark the row PARKED, cite it in the relevant ADR's Consequences section, and add a re-evaluation trigger.

The graduation rule is what keeps the register from becoming a dead list.

Canonical example

# Open Questions -- Architecture

This file tracks unknowns that block or qualify upcoming architectural decisions.
Each row is owned by a named human and has a measurement plan.

| ID  | Question                                                | Decision needed by         | Blocker for                  | Current best guess (confidence)              | Measurement plan                                                                | Owner   | Status  |
|-----|---------------------------------------------------------|----------------------------|------------------------------|----------------------------------------------|---------------------------------------------------------------------------------|---------|---------|
| Q12 | Should we shard the user table?                         | When DAU > 50k             | ADR-0016 (Postgres adoption) | Yes, by tenant ID (medium)                   | Run a load test at 75k synthetic users on the staging Postgres; record p95.    | Priya   | OPEN    |
| Q14 | Multi-region read replicas -- needed for EU launch?    | 2026-08-15                 | ADR-0019 (regional routing)  | Yes (high) -- latency requirement is firm.   | Confirm latency budget with product; benchmark cross-region replication.       | Marcus  | OPEN    |
| Q07 | Will the queue handle 10x peak?                         | Resolved 2026-04-12        | (none)                       | Yes -- confirmed by load test on 2026-04-10. | Load test result: p99 < 200ms at 12x peak. Logged in test-run-2026-04-10.json. | Priya   | ANSWERED|

When Q07 was answered, the team did not write an ADR — the answer ("yes, the queue handles 10x") is a measurement, not a decision. Had the team chosen to oversize the queue based on that measurement, that choice would be the ADR.

Common failure modes

Routing — when this is not the answer

• "We've decided X" → ADR, not the register.
• "We've decided not to decide yet, and we've identified the trigger that will force the decision" → register row with a clear Decision needed by.
• "We don't know how to do X right now and don't intend to decide soon" → `SUPPORT.md` / FAQ / Discussions if it's user-facing; issue tracker if it's implementation.
• "We've decided to ship with this question unresolved" → ADR with the question PARKED in Consequences, plus a register row tracking the PARKED state and re-evaluation trigger.

Postmortem canon — blameless incident review

The canonical reference for postmortems. Load this when the user says "we had an outage last week," "write up the incident," or "schedule a postmortem."

A postmortem records what happened, why, and what changes the team commits to after a notable incident. It is blameless by construction — the document focuses on systems, processes, signals, and decisions, never on individuals.

Two sources, distinct roles

doc-master distinguishes the template (the file you fill in) from the cultural framing (the discipline that determines whether the document is useful).

doc-master writes from the PagerDuty template and links to the Google SRE chapter for the cultural framing.

Required sections (PagerDuty template)

A doc-master postmortem includes these sections, in this order:

1. Incident Summary — one paragraph: what, when, who saw it, severity. 2. Leadup — what was in flight before the incident: deploys, config changes, traffic shifts, dependency upgrades, holiday weekends. Factual, not causal. 3. Fault — the specific failure: which component, which mode, which contract was violated. 4. Impact — measurable customer effect: users affected, requests dropped, revenue lost, SLO budget consumed, regulatory implications. Use numbers. 5. Detection — how the team learned about it: alert, customer report, internal observation. Note the latency between the fault and detection. 6. Response — what the team did, in order. Who was paged. Which runbook fired. Where the response stalled. 7. Recovery — what restored service. Whether the recovery was clean (graceful rollback) or messy (manual intervention, lingering effects). 8. Timeline — UTC timestamps, single source of truth. Cross-references every other section. 9. Root Causes — Five Whys (or equivalent technique). Multiple causes are expected and named separately, not collapsed into one. 10. Action Items — what changes the team commits to, each with an owner, a due date, and a tracking ID. Avoid "improve monitoring" — name the specific dashboard, the specific alert, the specific code change. 11. Lessons Learned — what generalizes beyond this incident. What the team understands now that it did not understand before.

When to write a postmortem — predefined triggers

A postmortem is not discretionary. The team agrees the triggers in advance, in writing, and writes one for any incident that hits them:

If the trigger is subjective ("was that bad enough?"), the team will under-write postmortems for the incidents that matter most — the loud ones get one, the quiet expensive ones do not. Make the triggers boolean.

Blameless framing — the discipline

The cultural rule is: focus on systems and processes, never on people.

• "The on-call engineer ran the wrong command" → bad. Reframe: "The runbook documented two commands with similar names; the more dangerous one was listed first."
• "Alice forgot to update the config" → bad. Reframe: "The config change required manual coordination between three repositories with no enforcement."
• "We should have caught this in review" → bad. Reframe: "The review checklist did not cover this class of change; we are adding a check for X."

When a postmortem names a person, ask: would changing that person fix the problem, or would the next person hit the same trap? If the latter, the trap is the problem.

For the deeper framing — psychological safety, second stories, hindsight bias, the swap test — read the Google SRE Workbook Ch. 10 referenced above. doc-master does not reproduce that chapter.

Postmortem is not an ADR

A postmortem and an ADR are different documents with different audiences:

A postmortem may produce an ADR — for example, "Add a circuit breaker between the payment service and the fraud service" might appear as an action item in the postmortem, and then become a separate ADR that records the architectural choice. The two documents cross-link; they do not collapse.

Common failure modes

Routing — when this is not the answer

• "What to do during the incident?" → runbook (runbook-canon.md). The runbook is forward-looking; the postmortem is backward-looking.
• "Why did we pick this architecture in the first place?" → ADR (alternatives-catalog.md).
• "What's our incident-response process in general?" → Diátaxis explanation + a runbook for each alert class. Not a postmortem.
• "What customer-visible changes did we ship?" → changelog (changelog-canon.md), with a Security entry if the incident produced one.

Runbook canon — operational steps for paged incidents

The canonical reference for runbooks. Load this when the user says "we need a runbook for X," "what do we do when the queue backs up?", or "document our incident response for the database alert."

A runbook is for an on-call engineer being paged at 03:00 under stress. It assumes nothing: not that the reader knows the system, not that the reader is awake, not that the reader has time to read prose. Every step is copy-pasteable. Every step has an expected output. The reader's job is to follow, not to learn.

This is fundamentally different from a Diátaxis how-to guide, even though both are task-oriented:

One runbook per alert. If a single alert can mean three different things, you have three runbooks (or one runbook with a clearly labeled triage step that branches to three sub-runbooks).

Upstream source: PagerDuty Incident Response — open, copyable operational playbook the rest of the industry has converged on. The PagerDuty material is published under permissive terms; cite it as "PagerDuty Incident Response open templates," not as a product endorsement.

Required sections

A doc-master runbook has these sections, in this order:

1. Title — exactly the alert name / paging condition as it appears in the monitoring system. If the alert is db-replica-lag-high, the runbook title is db-replica-lag-high. No marketing prose, no rewording. The on-call engineer pastes the alert name into a search box and the right runbook comes up first.

2. Trigger — what fires this runbook:

• The exact alert ID (e.g., PD-INC-1042, prom-rule-name).
• The dashboard URL the alert links to.
• The customer-report channel if one exists.

3. Preconditions — what must be true before running the steps:

• Required access (which IAM role, which secret, which bastion).
• Required tools installed locally.
• Anything that would silently fail otherwise.

4. Steps — numbered, each step is a single action:

• Copy-pasteable — every command runs as written.
• Expected output — what success looks like, character-by-character if possible.
• What to do if the expected output is absent — point to the next step or to the Escalation section.
• One step per cognitive unit. Do not bundle.

5. Verification — how to confirm the incident is resolved:

• The dashboard signal that should return to green.
• The customer-facing check.
• The wait time, if there is one ("metrics propagate in 60–90 seconds").

6. Rollback — what to do if the steps make it worse:

• The exact revert command for each forward step.
• Whom to call if rollback fails.

7. Escalation — who to wake up, and when:

• Named alias (not a person — bus factor).
• The threshold ("after 15 minutes with no improvement").
• The next-tier alias.

8. Known false positives — patterns the on-call should recognize as "not a real incident":

• Specific symptoms that look like the alert but are not.
• Why they look similar.
• How to confirm it's a false positive (the test, not the heuristic).

9. Last verified — ISO 8601 date the runbook was last exercised end-to-end. If it has not been exercised in six months, treat it as stale.

Common failure modes

Canonical skeleton

````md

db-replica-lag-high

Trigger

• Alert ID: prom-db-replica-lag-high
• Dashboard: <link>
• Customer channel: #cust-incidents (search for replica lag)

Preconditions

• AWS access to the db-prod account.
• psql and awscli on your path.
• Bastion access -- VPN profile prod-bastion.

Steps

1. Confirm the alert is current -- open the dashboard above. Replica lag > 30s for > 5 minutes?

• Expected: red line above 30s on the replica-lag-seconds panel.
• If green, this is a stale alert. Acknowledge and stop.

2. Identify the replica:

   aws rds describe-db-instances --db-instance-identifier db-replica-prod

• Expected: status available.
• If failed or incompatible-parameters, skip to Escalation.

3. ... (one step per cognitive unit, copy-paste, expected output)

Verification

• Dashboard replica-lag-seconds returns under 5s and stays for 10 minutes.
• Customer report channel quiet for 15 minutes.

Rollback

• (Per forward step, the exact revert command and the verification it returns to green.)

Escalation

• After 15 minutes with no improvement: page db-oncall-tier2 via PagerDuty.
• After 30 minutes: page eng-leadership-oncall.

Known false positives

• A scheduled pg_dump at 02:00 UTC causes ~45s of replica lag for ~3 minutes. If the alert fires at exactly that window and clears within five minutes, acknowledge as expected.

Last verified

• 2026-04-12 (tabletop exercise)

````

Routing -- when this is not the answer

• "How do I deploy to staging?" → Diátaxis how-to guide, not a runbook. The user is not being paged.
• "Why does the system handle backpressure this way?" → Diátaxis explanation.
• "What was the call we made on circuit-breaker thresholds?" → ADR — the decision. The runbook executes; the ADR records why the threshold is what it is.
• "What happened during the 2026-05-12 outage?" → postmortem, not a runbook. See postmortem-canon.md.
• "What are all our alert IDs and severities?" → Diátaxis reference (an alert catalog), with each entry linking to its runbook.