Check Spec Coherence

When behavior is specified in one place and implemented in another, the two copies drift. The authoritative version lives in a design doc; the running version is hand-ported into prompt fragments, server logic, and frontend wiring. Then each gets edited on its own. A gate condition changes in the code; a marker is renamed in a prompt but not the spec; a must-have item the spec demands never makes it into the implementation. Tests stay green because they encode the same assumptions the code does. If you direct a build without reading every line of code, you cannot catch this by eye.

This skill reads both sides for one named unit of behavior and reports the gaps. It changes nothing — you decide what to fix.

How it works

You give it a spec — a path, or a shorthand resolved against a source-of-truth table in CLAUDE.md. An ambiguous argument stops and asks; no argument lists the available specs and asks which to check.

Then four steps:

• Read the spec. Pull out the load-bearing elements: behavioral rules per beat, conditional logic, required gates and ordering, the data the unit must gather, state markers and what triggers them, transitions, and permission gates. Voice and tone blocks are noted but deferred to a separate voice check — this skill confirms the code does not contradict them, it does not re-audit tone.
• Find the implementation. Locate the files by searching first for the spec’s markers, then the unit’s keyword, then falling back to the primary prompt and backend files. It states which files it read and why. If the implementation does not exist yet, it says so and stops — there is nothing to drift-check.
• Compare. Each rule, marker, gate, and transition is sorted into one of four buckets: implemented faithfully, implemented but drifted, not implemented, or in code but not in spec — that last one catching drift in the reverse direction, behavior the code performs that no spec calls for.
• Report. A fixed five-section template, with both the spec passage and the code quoted side by side so you can jump to each cited line and verify it. Empty sections print “None.” rather than vanishing, so you can see the skill actually looked.

The check is purely textual — read-only, no editing, no running code. Findings must be concrete and quoted. “The agent might not handle X” is not a finding; a spec line requiring a permission gate set against the prompt line that delivers advice without one is.

Use it on

Any unit of behavior that lives twice — a feature, an endpoint, a workflow, a state machine. Run it after an edit, when you suspect the code has wandered from what you reasoned through. Pair it with a separate voice or schema check and keep the boundary explicit, so each owns one concern.