Audit a Spec for Drift
Does the spec still describe what the code does?
Reports only — fixing is
, and an auditor that can edit can make its own findings disappear.
Format authority:
references/spec-format.md
.
When to use
- "Is this spec still accurate?"
- Before planning work against a spec nobody has touched recently.
- Suspicion that a journey does something the contract doesn't allow.
Not this skill: whether tests exist (
), updating the spec (
), classifying a bug report (
).
Workflow
1. Read the spec completely first
All behaviours, invariants, decision tables, and the flow contract. Form the expectation before looking at code — reading them together lets the code quietly redefine what the spec "meant".
2. Check each behaviour against the implementation
For every behaviour ID, find the code that produces it and classify:
| Verdict | Meaning |
|---|
| Matches | Code produces the described outcome |
| Drifted | Code produces a different outcome — the spec is now wrong |
| Missing | Badged 🟢 or 🟡 but no implementing code found |
| Unspecced | Code produces observable behaviour no behaviour describes |
| Badge wrong | Behaviour exists but the badge overstates or understates it |
Unspecced is the category people forget and it's often the most valuable: features grow paths nobody recorded.
3. Check invariants are actually enforced
For each invariant, find the code path enforcing it — and, more importantly, look for paths that bypass it. An invariant enforced in one mutation and not its sibling is a finding, not a match.
4. Check the flow contract against real navigation
For each transition: does the code implement it, with that guard, reaching that state?
Then the harder direction — what can the code do that the contract doesn't declare? Undeclared bypasses, skipped steps, a back path that loses state, an error path that dead-ends. This is what a flow contract exists to catch, so spend the effort here.
Report guard mismatches precisely: a guard the code checks more loosely than the contract states is a real defect even when nothing has gone wrong yet.
5. Verify before reporting
Confirm each finding against current code. Check whether shared middleware or a helper handles what looks missing. Drop anything already handled. Fewer verified findings beat a long speculative list.
6. Report
Group by verdict, most severe first. Each finding: behaviour or transition ID,
, what the spec says, what the code does, and which one you think is wrong — with a reason.
That last part matters. Drift has two fixes: update the spec because the change was intended, or fix the code because it wasn't. Say which you believe and why; don't leave a bare mismatch for someone else to decide blind.
End with: counts by verdict, and whether the front-matter roll-up status is still right.
Quality gate
Anti-patterns
- Only checking spec → code. Misses everything the feature grew.
- Reading code and spec together. Form the expectation first.
- Reporting a mismatch without a recommendation. Half a finding.
- Accepting an invariant as enforced because one path enforces it.
- Fixing during the audit.
Related skills
- — apply the fix this recommends
- — the test-side question
- — when drift came from a reported symptom