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

Audit checklist — per-section probes

The detailed probe set for adr-critique Phases 3 (missing-why), 4 (consistency), and 5 (LikeC4 drift). Walk these in order on every ADR under audit.

Per-section probes

Frontmatter / header

Frontmatter / body mirror

doc-master requires both sources to agree so the ADR renders edges in both parser families. Walk these probes for every ADR:

Backfill ADRs

A backfill ADR is detectable by tags: [backfill] plus backfilled-on: YYYY-MM-DD. Older records may use status: accepted (backfilled YYYY-MM-DD) or status: deprecated (decision reversed since); flag those for header migration to ADR Explorer-compatible status values without changing the body. These records have a small set of probes of their own — they are subject to all other probes in this file as well.

Context

Decision

Consequences

Compliance (if present)

Alternatives Considered

Notes

Phase 3 — missing-why interrogation

For each line in the Decision (or any section claiming rationale), apply this two-question test:

1. What business concern is this decision serving? (compliance, cost, latency, time-to-market, vendor risk, team capacity) 2. Which architectural characteristic does it optimize? (availability, performance, maintainability, scalability, security, observability)

A valid line answers both. An invalid line answers neither.

Phase 4 — consistency probes

Probe 1: supersession graph compatibility

For every superseding decision, confirm the new ADR has supersedes: ["X"] (or an equivalent YAML list) in its frontmatter. ADR Explorer-style parsers read frontmatter only — a reverse superseded by: note on X, a body line such as Related ADRs: [ADR-0004](0004-foo.md), or a link from the decision-log README.md index does not create the edge. Flag missing or scalar supersedes values, and flag any relationship that lives only in prose with a recommendation to promote it into frontmatter using zero-padded four-digit string IDs ("0004").

Probe 2: orphan amendments

For every id in amends: [X], confirm X exists and is accepted. An amendment to a non-existent, deprecated, or superseded ADR is a flag.

Probe 3: tension detection

Two ADRs are in tension when both are accepted, neither supersedes the other, but their decisions conflict. Walk the graph: for every pair of relates-to-linked ADRs, ask "do these claims sit cleanly side by side, or do they contradict?" Flag contradictions.

Probe 4: duplicate authority

If two ADRs both claim authority over the same component or characteristic ("ADR 0007 picks the auth provider"; "ADR 0019 also picks the auth provider"), one must defer. Flag for the architect to resolve via supersession or scope narrowing.

Probe 5: ghost references

The ADR references another ADR by number (e.g., "as in 0023") that does not exist or has a different topic. Flag.

Phase 5 — LikeC4 drift probes

Probe 1: component name mismatch

Compare every component name mentioned in the ADR text against names in the LikeC4 model. Case-insensitive substring match isn't enough — exact match preferred. Flag mismatches.

Probe 2: missing component

ADR mentions a component the LikeC4 model does not contain. Could be:

• The model is stale (update the model)
• The ADR uses a wrong name (update the ADR)
• The component lives outside the diagram's scope (update neither, note explicitly)

Probe 3: missing relationship

ADR claims A depends on B but the LikeC4 model shows no such edge. Same three possibilities.

Probe 4: contradicting kind

ADR talks about "the user-service container" but the LikeC4 model defines user-service as an externalSystem. Flag — the kinds disagree.

Reporting format

End-of-audit summary:

Audited: <path/to/NNNN-title.md>
Neighbors read: <list of ADR IDs>
Flags raised: <N>
Flags applied: <M>
Flags rejected by architect: <K>
Open items needing follow-up:
  - <one line per item>

Do not stamp the ADR with [audited] markers, dates, or signatures. The audit's value is in the diffs, not the metadata.