--- id: JosiahSiegel/claude-plugin-marketplace/adr-critique version: "4fbf0236" license: MIT install: manual updated: 2026-06-18 --- # adr-critique — adr-critique systematically reviews existing or inherited ADRs to identify violations of shared rules, gaps in business-to-architecture reasoning, and conflicts with neighboring decisions or LikeC4 models. Each issue surfaces as a single flag requiring architect sign-off before moving to the next, ensuring quality without bulk rewrites. Publisher: JosiahSiegel · Stars: 49 · Updated: 2026-06-18 Install (manual): `git clone https://github.com/JosiahSiegel/claude-plugin-marketplace` ## SKILL.md # 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: Violates: Rewrite: 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. flags raised, applied. open items: ." ## 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 [View on SkillFed](https://skillfed.io/JosiahSiegel/claude-plugin-marketplace/adr-critique) · [View on GitHub](https://github.com/JosiahSiegel/claude-plugin-marketplace)