JosiahSiegel/adr-critique

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:

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