doc-diagnostic

What this skill does

# 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](https://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:

| Template          | Use when...                                                                                | Don't use when...                                |
|-------------------|--------------------------------------------------------------------------------------------|--------------------------------------------------|
| **Nygard / MADR light** | Decision is simple, alternatives obvious, three to five fields suffice (Context, Decision, Consequences). | You need to compare 3+ alternatives on multiple criteria. |
| **MADR (full)**   | Multiple options need side-by-side analysis; decision drivers matter; Confirmation/Validation field needed; traceability matters. | The decision is trivial -- full MADR pads it. |
| **Y-statement**   | One sentence: *"In the context of X, facing Y, we decided Z, to achieve W, accepting that V."* Good for compact log entries or executive summaries. | The decision needs structured fields. |
| **arc42 / Tyree-Akerman / Business case** | The project already uses one. | Starting fresh -- heavier than most teams need. |

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

### Canonical status lifecycle

```text
  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 n