---
name: spec-audit
description: A read-only audit of a project's specs against the work that just landed. Use when a batch, feature or set of changes has been merged or is about to be pushed, when the user asks whether a spec is up to date, accurate or drifted from the code, or before a design discussion leans on a spec's text. Not for writing a new spec or design document, reviewing a design document, reviewing code for bugs, or planning work that is not built yet.
license: MIT
---

# Spec audit

> **Invoke:** `/spec-audit <range or effort>`. The session briefs one read-only background agent with
> `AUDIT-BRIEF.md`, spot-checks its report, triages each finding and names who acts on it. It edits no spec,
> files nothing and changes no code.

This skill produces one audit report: findings in four kinds, each with its evidence, and a triage line per
finding. It does not fix specs, file tracker entries or change code; those are handoffs, named at the end. The
pull to "just fix this one line while here" is the signal to stop and hand off, because an audit that edits is
no longer independent of what it audits.

## The rule the audit enforces

A spec is an **exact description of what the code does**, not a plan.

- **The code is right by default.** Built behaviour no spec describes stays as it is and is recorded as a gap.
  Changing or deleting built behaviour to match a spec is the user's decision, never the audit's.
- **Planned work does not live in a spec.** It goes in the project's tracker, and its design in the project's
  design documents. A spec section marked planned, future, TODO or "will" is itself a finding (kind D).
- **A design document is not a spec.** The audit covers specs only. A design document's planned text, later
  work and verification list are not findings; read it only to tell what was meant from what was built.
- **A built feature moves from its design document into the spec.** Its built parts become spec text that
  describes the code exactly, and the design document is marked built or cut to what remains unbuilt. A built
  part described only in a design document is kind A.
- **A change to specified behaviour updates the spec in the same change.** The audit checks that it did; it
  does not replace that step.

A plan-style spec tends to let planned items fall through: nobody owns text that reads as already decided.

## When

- After a batch, feature or set of changes lands, ideally before it is pushed or released.
- When the user asks whether a spec is current.
- Before a design discussion that will rely on a spec's text.

## Running it

1. **Gather the inputs.** Ask the user, in one round, only what they know and the repository does not show:
   - the base of the range (the last commit before the effort began), if it is not obvious;
   - one line on what the effort built;
   - which spec files to audit, if the project has no obvious set (specs only, not design documents);
   - which areas are being changed right now and so are out of scope.
   Find the rest yourself: the commit list (`git log --oneline <base>..HEAD`), the spec files, the design
   documents for what the effort built, and the open tracker entries about spec drift. If the user is not there
   to answer, use the last tag or merge before the effort as the base, all files named like specs, and say so
   in the brief as a stated assumption.
   *Gate:* a base commit, a spec list and an out-of-scope list exist, even if empty. No range, no brief.
2. **Size it.** Count the commits and the changed lines. Expect about an hour for a strong model on a range of
   a few dozen commits. If the diff is too large for one careful read, split by spec file or by sub-range and
   brief one auditor per piece, with no overlap between them.
3. **Brief one auditor** with `AUDIT-BRIEF.md`, filled in. Use a strong model, read-only, in the background.
   Keep the brief's structure and its report template; fill every slot or write "none".
   With no subagents, run the audit yourself in a fresh context, read-only, using the same brief, and say so in
   the report.
4. **Spot-check the report.** Open two or three of its file:line citations on each side (spec and code) and
   confirm they say what the report claims. Check that every finding has its required fields and that nothing
   unverified sits in A-D.
   *Gate:* no spot-check, no relay. If a citation is wrong, check the rest of that kind before relaying, and
   say in the relay which findings were corrected.
5. **Triage and relay.** Add a triage line to each finding from the table below, then give the user the
   counts per kind, the findings, and the two handoffs.

## The four kinds

| kind | meaning | required evidence |
|---|---|---|
| **A** | built, but in no spec | a title as a present-tense claim (80 characters or fewer), an area, the code file:line, and the spec section that should hold it |
| **B** | in a spec, but not built | spec file:line, and whether the spec is stale or the code is missing, with the evidence for which |
| **C** | stale or wrong spec text | spec file:line, a short quote, and what the code does instead (code file:line) |
| **D** | planned text inside a spec | spec file:line, a short quote, and the tracker entry it belongs to, if one exists |

Within each kind, rank by how badly the text would mislead a reader who trusted it. A claim the auditor could
not confirm either way goes in a separate **Unverified** list, never in A-D.

## Triage

| kind | what happens |
|---|---|
| A | one tracker entry each, at high priority, marked as part of the effort; a defect if the behaviour itself looks wrong, otherwise a chore. The code stays. The spec-fix change then describes it; where a design document describes it, that change also marks the design document built or cuts it to what remains. |
| B, stale spec | goes into the spec-fix change |
| B, missing code | one tracker entry at normal priority; the spec text moves out to that entry and the design documents |
| C | goes into the spec-fix change |
| D | the plan moves to its tracker entry and the design documents; the spec keeps only what is built |

## Handoffs

- **Filing.** Whoever owns the project's tracker files the A and B-missing entries. If the project has no
  tracker, the findings stay in the report for the user to act on; say so.
- **The spec-fix change.** One docs-only change, by a separate agent or the user, listing the A, B-stale, C
  and D findings with file:line. Its brief says to describe the code exactly as it is, never what it should be.
  It is required whenever any A, B-stale, C or D finding exists.

A spec cites code by symbol (a type, function or constant name), not by file:line, so a rename or removal
fails loudly in search or a check rather than leaving a stale line number. The audit report uses file:line,
because it is read once, now.

## Done when

- [ ] The report has all four kinds and the Unverified list, each filled or marked "none".
- [ ] Two or three citations per side have been opened and confirmed, and any correction is stated.
- [ ] Every finding has a triage line.
- [ ] Every A finding has a tracker entry, or the user has been told it has none yet and why, with the ids
      given where they exist.
- [ ] The spec-fix change is briefed or handed to the user, if any A, B-stale, C or D finding exists.
- [ ] The effort's record notes the audit: its range, its counts per kind and the entry ids.

## Pitfalls

- **Auditing the messages, not the diffs.** A commit message says what was meant; the diff says what was
  built. The auditor reads the diff of each commit.
- **"The spec is right, the code drifted."** This reads as diligence and reverses the rule. Built behaviour
  stays; the finding is kind A or C, and any change to the code is the user's call.
- **Vague claims.** "Section 3 is out of date" cannot be acted on. Every finding names a line on each side.
- **Reporting twice.** Areas mid-change and drift already in the tracker go in the brief, so the auditor
  extends existing entries rather than repeating them.
- **Relaying unchecked.** Citations can drift by a few lines or describe an older revision. Check before the user
  sees them.