Spec drift

Spec Drift

A spec is only worth having if it's true. The moment the code and the document disagree, the document stops being a reference and becomes a liability — because people still trust it.

Your job is to find every place they disagree and, for each one, answer the only question that matters: which side is wrong?

The rule that makes this safe

Updating the spec to match the code is the dangerous default. It is fast, it always "resolves" the gap, and it silently blesses every regression as intended behavior. Do it wrongly once and the spec now documents the bug.

So:

A gap against a section that recorded a reason is a regression until proven otherwise.

§3 Decisions, §8 Edge Cases, and §9 Security exist precisely because someone thought about them and wrote down why. If the code contradicts one of those, the overwhelmingly likely story is that a later session didn't know. Treat it as a bug in the code, and make the user actively override you to rule otherwise.

A gap against a section that merely describes — a field that got added, an endpoint that got renamed — is ordinary staleness. Update the spec.

---

Workflow

Phase 0 — Find the spec

Look for docs/SPEC.md, then SPEC.md, then any *.spec.md in docs/. If there's more than one, ask which.

If there is none, stop and say so — offer spec-architect to write one. Do not invent a spec to check against; a reconstructed spec compared to the code it was reconstructed from finds nothing.

Note the spec's Status: line if it has one. A spec last touched six months and forty commits ago will drift heavily, and the report should open by saying so rather than dumping ninety findings.

Phase 1 — Extract checkable claims

Most of a spec is prose that no tool can verify — "shift managers rebuild the schedule in Excel" is context, not an assertion about the code.

Read references/checkable-claims.md. It lists, per section, exactly what can be mechanically confirmed and how to confirm it. Work only from that list. Inventing checks produces confident findings about things the spec never claimed, which is the fastest way to make this skill untrustworthy.

Roughly, the checkable surface is:

Section	What can actually be verified
§3 Architecture	Named components exist; forbidden dependencies absent
§4 Conventions	Directory layout, dependency direction, naming, size limits
§5 Data Models	Every field, type, nullability, constraint, index
§6 Interfaces	Every endpoint / channel / command, and its payload
§8 Edge Cases	The handling each case specifies is present in code
§9 Security	The stated enforcement point exists and is actually used

Phase 2 — Verify

For each claim, go find the truth in the code. Read files; don't infer from names. A finding you cannot point at a file and line for is not a finding — drop it.

Search widely before concluding something is missing. An endpoint absent from routes/ may be registered in a plugin file; a constraint absent from the model may live in a migration. Reporting a false "missing" trains the user to ignore the whole report.

Phase 3 — Classify each gap

Read references/verdicts.md. Every gap lands in exactly one bucket:

Regression — the code contradicts a section that recorded a reason. The spec is right; the code broke. Highest priority, always reported first, and each one names the reason it violated so the user can see what was lost.

Staleness — the code did something new or different, and no stated reason forbade it. The spec is out of date. Update the document.

Undecided — both sides changed, or the spec's own intent is ambiguous. Do not guess. Present both readings and let the user pick.

If a gap doesn't clearly fit, it's Undecided. Forcing a verdict is worse than admitting one is needed.

Phase 4 — Report before touching anything

Show the whole picture first. Regressions at the top, then staleness, then undecided. For each:

§8 Edge Cases — "endMinute may exceed 1440 for overnight shifts"
   src-core/domain/shift.rs:47   rejects endMinute > 1439

   REGRESSION. The spec recorded why: a night shift that runs 22:00 → 06:00
   is otherwise unrepresentable, and overlap detection silently stops working.
   The validation added here reintroduces exactly that bug.

   → Fix the code (remove the upper bound, keep 0 ≤ startMinute ≤ 1439)
   → Or: the requirement genuinely changed — update §8 and say what replaced it

Every entry carries: the spec claim, the file and line, the verdict, and the concrete fix for each direction. Never present a gap without a recommendation — an unranked list of forty differences is the same as no report.

Then let the user choose. Batch the decisions into one AskUserQuestion call where the tool is available; don't walk through them one at a time.

Phase 5 — Apply

Fix only what the user accepted.

• Fixing code: make the minimal change that satisfies the spec claim. If the fix is larger than a few lines, say so and stop — a drift check is not a refactor.
• Updating the spec: edit the section in place, keep its voice and structure, and never delete a recorded reason. If a Decision genuinely reversed, rewrite it as a Decision with the new choice and what changed — the record of why is the most valuable thing in the document, and quietly dropping it is how a spec turns back into prose.
• New things with no home: a component or endpoint the spec never mentioned gets added to the right section, not appended to the end.

Finally, bump the spec's version or date line if it has one, and report what you changed on each side.

---

Calibration

Match the report to the drift. A spec checked weekly should usually come back clean — say so in one line and stop. A spec untouched for months against an active codebase will have real divergence; lead with the three findings that matter and summarize the rest rather than producing a wall.

Silence is a valid result. "No drift found across §4, §5, §6, §8, §9" is a useful thing to be told. Never manufacture findings to look thorough.

Reference files

• references/checkable-claims.md — per section: what is verifiable, and how to verify it
• references/verdicts.md — classifying each gap, and how to write the fix on either side

Related

spec-architect writes the spec this skill checks. If the project has no spec yet, that's the one to run first.