---
name: spec-audit-drift
description: Audit a feature spec against the actual implementation to find where behaviours or user-flow contracts no longer match the code. Use when the user says "is this spec still accurate", "check the spec against the code", "I think this wizard bypasses the documented flow", or before relying on a spec that hasn't been touched in a while. Reports only. Pairs with spec-assess-coverage, which asks whether tests exist.
---

# Audit a Spec for Drift

Does the spec still describe what the code does? **Reports only** — fixing is `spec-maintain-on-ship`, and an auditor that can edit can make its own findings disappear.

Format authority: [`references/spec-format.md`](../../references/spec-format.md).

**Not this skill:** whether tests exist (`spec-assess-coverage`), updating the spec (`spec-maintain-on-ship`), classifying a bug report (`spec-triage-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 and spec differ; establish which side should change |
| **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.

Check storyboard coverage before its content. Once a flow uses storyboard evidence, every `screen` and `terminal` state requires a `storyboard` block; report each missing block as drift before checking the scenes themselves.

For every storyboarded screen, terminal, or visible action/processing state, inspect implementation and available evidence to establish whether the journey communicates the declared goal and information, exposes the named primary transition where applicable, provides the stated feedback, preserves the promised work, and follows the recorded accessibility behaviour. Do not turn visual preference into a requirement.

Reuse evidence under [write-tests](../write-tests/SKILL.md). Run a focused browser check only when needed and permitted by task/repository policy; otherwise report the evidence limit. This audit does not automatically start the app or full test suites.

### 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, `file:line`, 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.

## Related skills

- `spec-maintain-on-ship` — apply the fix this recommends
- `spec-assess-coverage` — the test-side question
- `spec-triage-bug-report` — when drift came from a reported symptom