Spec To Code Compliance

Spec-to-Code Compliance

Two artifacts disagree, and the job is to find where. The documentation says what the system does; the code decides what it actually does. Every gap between them is either a bug or a documentation fix, and which one it is is the finding.

When to Use

You have both documentation describing intended behavior and the code that should implement it. A whitepaper against a protocol, a design note against a service, a README's stated guarantees against the functions behind them.

Most useful when the document is authoritative — something a client wrote, published, or is audited against — because then a divergence is a defect rather than stale prose.

When NOT to Use

Not for code with no documentation of intended behavior. There is nothing to check against, and a requirement inferred from the code is checked against itself. Build the system model first with audit-context-building.

Not for finding bugs in general. This finds one class: where the code and the document disagree. A bug both artifacts are silent about is out of scope, and a bug the document endorses is a finding against the document.

Not for writing or improving documentation, though it produces the list of what needs fixing.

Do not check requirements in this context

Run /spec-to-code-compliance:spec-compliance <path>. The slash command takes a path; to name the specification directly or widen the fan-out, ask for the run with those values — "run spec-compliance on ./contracts against SPEC.md, checking 20 requirements" — and they reach the script as {path, spec, limit}. Typing the object literally after the slash command does not work; it arrives as a string and becomes the path.

It finds the documents, splits them into individually checkable requirements, gives each requirement its own agent to hunt the code with, has independent agents try to refute every divergence before it is reported, and writes spec-compliance/REPORT.md plus one file per requirement under spec-compliance/requirements/. Only compact records come back here.

For a single requirement, dispatch the spec-to-code-compliance:spec-compliance-checker agent at it.

This is not a preference about where output lands. The check does not fit in one context window if it is done honestly: judging one requirement means reading the enforcement, its callees, and its callers, and doing that for thirty requirements means holding thirty call chains at once. Attempted inline, the first few get a real check and the rest get a plausible one — and the transcript looks the same either way, because a verdict resting on a promising function name reads exactly like one resting on having read the function. Per requirement, in its own context, is what makes that difference visible.

Two properties come from the script rather than from instructions, and cannot be had here:

• A refutation the finding's author did not perform. Claude favors findings it produced when asked to check them. The workflow sends each divergence to agents that did not produce it — one reading the code again, one re-reading the document — and drops what either knocks down.
• Records that cannot be prose. A subagent bound to a return schema has to name the lines it read and the searches it ran. An absent verdict arrives with the patterns tried and their results attached, which is the only thing separating a real absence from a search that stopped early.

Measured on the routes-not-inline eval: with this plugin installed the work is dispatched every run, without it never — Δ +1.00. Deleting this section while leaving the workflow in place changes nothing, because the workflow is a real command that gets found and dispatched on its own. Read that as the mechanism carrying the behavior rather than this text: the section is here so a human knows what runs and why, not because the routing depends on it.