Audit
Are we still on course? Lint the decisions and judge the code in one run. Use for ADR audit, architecture drift, a whole-codebase compliance check, or a governance report. Read-only.From its SKILL.md
npx -y skills add rvdbreemen/adr-kit --skill auditAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 4 stars4 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
4.4 KB, as published. Nobody here has run it
ADR Audit
Use $ARGUMENTS to pick the scope. Empty means the whole codebase, because
that is the question people mean when they ask whether the project is still on
course. Read-only: this skill reports, it never edits an ADR or a source file.
Why one command for two questions
Two answers are needed and either one alone is misleading:
- Are the decisions any good? A clean judge over vague ADRs proves nothing, because a vague rule cannot be violated.
- Does the code obey them? A sharp ADR set nobody checks the code against is documentation, not governance.
bin/adr-audit runs adr-lint and adr-judge together so the caller does not
have to know the answers come from two binaries.
Run it
# The whole codebase: every tracked file judged as if newly added, so forbid
# rules reach code no recent diff touched.
"$ADR_KIT/bin/adr-audit" --whole-codebase --adr-dir docs/adr --repo-root .
# A specific diff: the hook and pull-request case.
git diff --unified=0 origin/main...HEAD | "$ADR_KIT/bin/adr-audit" --diff -
# Machine-readable, for a CI job or another tool.
"$ADR_KIT/bin/adr-audit" --whole-codebase --format json
Add --llm to include the judge's LLM pass for llm_judge ADRs. It costs
money and time proportional to the number of opted-in ADRs, so confirm with the
user before adding it — never on your own initiative.
Read the exit code before you read the output
The two failures have different owners, so they have different codes:
| Exit | Meaning | Who fixes it |
|---|---|---|
| 0 | on course | nobody |
| 1 | the code violates an Accepted ADR | the author of the code, or supersede the decision |
| 3 | the ADR set fails its own gates | the author of the records |
| 4 | both | both, and report them separately |
| 2 | the audit could not run | tooling or configuration; it did not answer "no" |
Never collapse 1 and 3 into "the audit failed". Say which one, and to whom it belongs. Exit 2 is not a finding: report that the audit could not run and why, and do not present its silence as a pass.
Responding to findings
- Code violations — cite ADR, file and line. Offer to fix the code, or, if
the decision itself is what is wrong, to supersede it with
/adr-kit:adr. Never work around an Accepted ADR silently. - ADR-quality failures — name the failing gate, not just the ADR. Offer
/adr-kit:grill ADR-NNNfor a Proposed record. An Accepted record's body is immutable: the honest routes are a supersession or a retirement, never a rewrite. - Whole-codebase mode surfacing old violations — expected and worth saying plainly. A rule added after a file was written has never been applied to that file. Offer a remediation task rather than a large unrequested edit.
Which gates a green audit covers
By default the lint half runs completeness, audit and consistency -- the
structural gates, which have exact answers. A green audit at the default set
is not a statement that the records are sharp, and this command's own
rationale turns on that distinction: a clean judge over vague ADRs proves
nothing, because vague rules cannot be violated.
--gates passes a set through to adr-lint. --gates all adds schema,
evidence, clarity, policy and quality.
| Question | Gate set |
|---|---|
| Are the records structurally sound? | default |
| Are they sharp enough to be violated? | --gates all |
| Would they survive release? | --strict |
Say which set produced the answer when you report it. "The audit is green" is a different claim depending on the set, and the reader cannot tell from the verdict line alone.
Where it fits
/adr-kit:judgejudges one staged diff at commit time. Narrower and faster./adr-kit:lintchecks the records alone./adr-kit:guardianruns a version of this combination on a cadence./adr-kit:auditis the on-demand form a person, a hook or a CI job can simply demand, and the only one that reaches code no diff has touched.
bin/adr-discover is a different thing despite the old name: it is the init
scanner that looks for decision-shaped artefacts. It does not audit anything.