adr-policy

name

adr-policy

description

Review-time policy check for pull requests that touch `docs/adrs/`. Surfaces the deterministic ADR immutability gate (`scripts/adr-immutable.mjs`) and adds the judgment checks a script cannot own: re-litigation of settled decisions, `supersedes` pointer correctness, and summary honesty. Scope is ADR log integrity and decision judgment only — the ADR files, their frontmatter, and git history. Docs-match-the-code is doc-drift's job, not this skill's. Triggers on phrases like "adr policy", "check this ADR", "review the ADR change", "is this ADR re-litigating", "is supersedes correct". Also invocable via the `/adr-policy` slash command.

ADR Policy

Reviews changes to the ADR log under docs/adrs/ at review time. The ADR model is an immutable event log with two projections (architecture docs, generated index).

Enforcement is split by what needs judgment. This skill owns log integrity and decision judgment. It does not rewrite ADRs — it surfaces findings, the user decides.

Scope: the ADR log only

• In scope: files under docs/adrs/, their frontmatter, and the git history of the diff (base-to-head).
• Out of scope: whether the architecture docs match the code — that is doc-drift. Never flag docs-vs-code drift here.
• Out of scope: whether some code "should have an ADR." ADRs are filed by humans before work begins; coverage is never this skill's call.

Read discipline

ADRs are human-first; agent reads are gated to authoring and recompiling. A review pass is an authoring-adjacent read: read docs/adrs/index.md first, then open only the ADR files changed in the diff and any record a changed ADR points at (its supersedes target). Never read the log wholesale to understand the current system.

What this skill checks

1. Immutability (deterministic — surfaced, never re-judged)

The one invariant the read model rests on — an accepted ADR body is never rewritten — is owned by a standalone deterministic script, never by an LLM. Run it and surface its result verbatim:

node scripts/adr-immutable.mjs --merge-base

Report its pass/fail as the first line of the ADR section so everything lands in one place. Do not second-guess it, soften a failure, or re-derive the verdict by reading diffs yourself. One check, multiple surfaces: this skill is a surface, not the owner.

2. Re-litigation (judgment)

Does a new or changed ADR re-decide something already settled — or already superseded — without acknowledging it? Scan the index one-liners for records covering the same decision space. If the new ADR reverses or narrows a live decision, it must point at it with supersedes; if it merely restates a settled one, that is churn. Flag either.

3. supersedes correctness (judgment)

When a changed ADR carries supersedes: NNN:

• Does id NNN exist, and is it the record actually being replaced (not a sibling or a record already superseded by a third ADR)?
• Is the superseded decision genuinely the live one this ADR overrides? A forward link aimed at the wrong record silently corrupts the derived status the index shows.

4. Summary honesty (judgment)

Does the one-line summary frontmatter state what the Decision body actually decided? The summary is projected into the index and read instead of the record most of the time, so a summary that oversells, hedges, or describes a different decision than the body is a defect — it steers readers wrong at the cheapest, most-read layer.

Report

Produce one ADR section:

• Immutability — the script's verdict, verbatim. ✅ or the ❌ lines it printed. A ❌ here is blocking; the deterministic gate fails the build regardless of this skill.
• Judgment findings — every re-litigation / supersedes / summary issue, with the ADR file and the specific frontmatter field or body claim it concerns, and the question the human must answer. These are surfaced, not blocking.

If nothing is wrong, the section is just the immutability ✅ line.

Guidelines

• Read-only. Never edit ADRs; propose, the user decides. Fixing a re-litigation or summary problem means authoring or amending an ADR through the /adr flow, not editing here.
• Never own immutability. The script is authoritative. This skill only relays it.
• One pass with doc-drift. On a PR touching docs/adrs/ or docs/architecture/, the code-review agent runs this skill and doc-drift together and folds both into one report. This skill covers the log; doc-drift covers the docs. They stay separate to keep single responsibility.