adr-critique

What this skill does

# adr-critique

Line-by-line auditor for legacy / external / pre-existing ADRs. Surfaces violations of the shared "ADR is not" rules, missing-why reasoning, inconsistency with neighbors, and drift against LikeC4 models. Touches only architect-approved lines.

## When to use this skill

- ADRs that predate `adr-drafting` (legacy corpus)
- ADRs imported from other teams
- ADRs generated by generic LLM tooling without push-back
- Periodic corpus-wide quality sweeps

## When NOT to use this skill

- ADRs already self-critiqued by `adr-drafting` (Phase 6) — they've been through the filter.
- ADRs you want to **rewrite from scratch** — use `adr-drafting` instead and supersede the original.

## Style rules

- **Quote offending lines verbatim.** Never paraphrase what the ADR says. The architect must see the exact text being criticized.
- **Name the specific rule broken.** Reference the section of `../_shared/adr-is-not.md` (e.g., "Rule 5 — generic best-practice citation").
- **Rewrites must be shorter than originals.** If a rewrite is longer, it's a redraft, not a critique — route to `adr-drafting`.
- **One flag per message.** Never bulk-list violations. Require per-line architect approval.
- **No affirmations.** No "Great ADR overall, just a few nits." No "This is a solid decision." The audit either finds problems or it doesn't.

## Vocabulary

- **Component** — a C4 Container (deployable unit), not a code class.
- **Architectural characteristic** — the non-functional quality being optimized (latency, cost, maintainability, etc.).
- **Tension** — two ADRs conflict without one superseding the other; must be acknowledged.
- **Missing-why** — the Decision section's justification leans on "best practice" or "industry standard" instead of mapping a business concern to an architectural characteristic.
- **Drift** — the ADR and the LikeC4 model disagree on which components exist or how they relate.

## The six phases

### Phase 1 — Read

Load the target ADR. Then glob its neighbors via `supersedes`, `amends`, and `relates-to` links and read each. The audit needs the graph context.

If the ADR cites a LikeC4 file, glob `**/*.c4` and read the referenced model.

### Phase 2 — Line-by-line flagging

Walk the ADR top to bottom. For every line that violates a rule, emit **one** flag using this template:

```yaml
Original: <verbatim line from ADR>
Violates: <rule number and name from adr-is-not.md, OR "missing-why" / "drift" / "tension">
Rewrite:  <shorter, stricter replacement -- or "delete">
Apply?    (yes / no / adjust)
```

Wait for the architect's reply. Only after they answer do you move to the next flag.

If the architect chooses `adjust`, accept their rewrite (still subject to the shorter-than-original constraint).

### Phase 3 — Missing-why check

Focus on the Decision section. Valid reasoning ties a **business concern** to an **architectural characteristic**. Invalid reasoning includes:

- "This is the industry standard."
- "This is a best practice for microservices."
- "Most teams do it this way."
- "It's the recommended approach."

For each invalid line, flag it with `Violates: missing-why`. The rewrite either supplies the missing tie ("Because compliance requires data residency in EU, this DB offers per-region replicas") or deletes the line.

See `references/audit-checklist.md` for the full missing-why interrogation.

### Phase 4 — Consistency check

Across the ADR and its graph neighbors, look for:

- **Tensions** — two ADRs claim incompatible decisions without one superseding the other. Flag both and ask which supersedes.
- **Missing relationships (frontmatter)** — a later decision claims to replace 0004 but lacks `supersedes: ["0004"]` in its frontmatter; related/amended links are not valid YAML lists; or the only evidence of a relationship lives in a body line such as `Related ADRs: [ADR-0004](0004-foo.md)` or in the decision-log `README.md` index. Gray-matter-style parsers read frontmatter only — body-only links and index links do not produce graph edges for that parser family. Flag every prose-only relationship for promotion into frontmatter (`supersedes` / `amends` / `relates-to`) with zero-padded four-digit string IDs.
- **Frontmatter / body mirror mismatch** — doc-master requires the two sources to agree. Flag each of the following:
  - Frontmatter populates `supersedes`, `amends`, or `relates-to`, but the body has no `## More Information` section with a `### Relationships` sub-section mirroring those relationships using the doc-master link-prefix vocabulary (`Supersedes`, `Superseded by`, `Amends`, `Amended by`, `Related to`). These ADRs are invisible to body-scanning parsers (ADR Manager and similar).
  - The body has a `### Relationships` section listing ADR-to-ADR links, but the corresponding frontmatter relationship keys are empty or absent. These ADRs are invisible to gray-matter-style parsers (ADR Explorer and similar).
  - The two sources disagree on the set of relationships (e.g., frontmatter `supersedes: ["0004"]` but body `Supersedes [ADR-0005]`). Flag the discrepancy and ask which is correct.
- **Duplicate authoritative claims** — two ADRs claim authority over the same component/decision. One must defer.

See `references/audit-checklist.md` for the consistency probes.

### Phase 5 — LikeC4 drift check

Glob `**/*.c4` and any `likec4.config.*`. Compare component names referenced in the ADR with the LikeC4 model:

- ADR mentions a component the C4 model doesn't have → surface as drift, ask which source is canonical.
- C4 model has a component the ADR contradicts → surface as drift.

Do **not** auto-update either. The architect picks which side is the source of truth.

### Phase 6 — Apply approved changes

Once all flags are resolved, apply the architect-approved edits in **one** edit pass:

- Touch only approved lines.
- Do not add audit markers, `[reviewed]` stamps, or commentary in the file.
- Preserve frontmatter and structural sections.
- If the ADR is `accepted`, **do not** edit the body — instead, draft a new ADR that supersedes it. The audit can recommend supersession but cannot perform it silently.

## Output discipline

- **Never bulk-edit.** Per-line approval is the discipline that keeps the audit useful.
- **Never edit an Accepted ADR's body.** Allowed edits to an Accepted ADR: typo fixes, graph-compatible header fixes, metadata-only relationship-link fixes explicitly permitted by the project's governance, adding a human-readable `superseded by` note in the header, or adding a dated "Amendments" note at the bottom under an explicit heading. Anything else is a new ADR.
- **Surface, don't decide.** Tensions, drift, and missing-why are flagged; the architect decides how to resolve.
- **Report at the end.** After applying changes, emit a one-line summary: "Audited NNNN-title.md. <N> flags raised, <M> applied. <K> open items: <list>."

## References

- `references/audit-checklist.md` — the full per-section probe set used in Phases 3-5
- `../_shared/adr-is-not.md` — the canonical rule set referenced in flag `Violates:` fields
- `adr-drafting` skill — for ADRs being drafted fresh, not audited
- `c4-model` skill — for resolving LikeC4 drift surfaced in Phase 5