# Spec Sheet — Check Spec Coherence

**What you are building:** A read-only project skill that compares a behavior spec against the code implementing it and reports drift between the two — in evidence the reader can verify line by line.

> Bracketed [PLACEHOLDERS] are yours to fill for your own project. This skill has no embedded credentials, but if you adapt it into one that does, never inline a secret — supply it from your own secret store and reference it generically.

## 1. Purpose

You have a system where some behavior is specified in authoritative design documents and separately implemented in code (prompt fragments, server logic, frontend wiring). The two copies drift as each is edited independently. This skill reads both sides for a named unit of behavior and reports where they disagree, classified into four buckets: drifted, not implemented, present in code but absent from the spec, and faithfully matched. It is diagnostic only — it never edits, never runs anything, and leaves the fix decision to the user.

## 2. Activation — name and description

**Name:** `[check-spec-coherence]` (or your own verb-noun, e.g. `[verify-spec-drift]`).

**Description** (this is what makes the model auto-trigger — be explicit about the trigger phrases and conditions):

> Compare a [UNIT] spec against the code that implements it and report drift. Use when the user runs /[skill-name], or asks to check that a [UNIT]'s implementation matches its spec, or to audit whether code drifted from a spec after edits.

Include in the description: the slash-command form, the phrase "matches its spec," and the after-an-edit audit case. Those three are the realistic trigger surface.

## 3. Inputs and preconditions

- **One argument:** a path or shorthand identifying the spec to check.
  - Full path: `[Specs/Area/feature-spec.md]`.
  - Shorthand: a keyword (`[feature-a]`, `[feature-b]`) resolved against a lookup table.
  - Full slug: `[feature-area-name]`.
- **Shorthand resolution table** must exist somewhere the skill can read — recommended: a "source of truth" table in the project's `CLAUDE.md` mapping each behavior unit to its spec file.
- **Ambiguous argument** (matches several specs): list the matches, ask which, do not proceed.
- **No argument:** list the available specs from the table and ask which to check. Do not proceed.

## 4. Outputs and side effects

- **One structured report**, returned in the conversation. Nothing is written to disk.
- **No side effects.** No file edits, no git operations, no servers, no code execution.

## 5. Environment and dependencies

Generalized, the skill assumes:

- A **spec corpus** of authoritative design documents (the source of truth for behavior).
- An **implementation tree** where that behavior is realized, typically split across: a prompt or config layer, a backend/assembly layer, and a frontend/handler layer. Name yours.
- A **source-of-truth index** (a table in `CLAUDE.md` or equivalent) mapping each behavior unit → its spec path, used for shorthand resolution and the no-argument listing.
- A **convention for state signals / markers** in your system (named tags, sentinel strings, enums) that appear in both spec and code and are the highest-signal things to diff.
- No MCP tools, no network, no credentials required. Pure file reads plus text reasoning.

## 6. Procedure

1. **Resolve the argument.** Map shorthand → spec path via the source-of-truth table. If ambiguous, list and ask. If absent, list available specs and ask. Stop in both cases.

2. **Read the spec in full.** Extract the load-bearing elements:
   - Behavioral rules per step/beat, and conditional logic ("if X then Y").
   - Required gates and ordering ("must do X before Y").
   - Data the unit must gather: must-have, optional, and items that gate downstream units.
   - State markers / signals — record each marker's name and what triggers it.
   - Transitions/handoffs and their trigger conditions.
   - Permission gates (points where the system must explicitly ask before acting).
   - Any special sub-systems your specs carry (e.g. conditional paths, fallback logic, platform adaptation) — note whether the implementation supports them.
   - Voice/tone/style blocks: **record their presence but defer the judgment** to a separate voice/style check; here, only confirm the code does not contradict them.

3. **Identify the implementation files.** Locate the code that realizes this unit by, in order:
   1. Searching the codebase for any markers the spec defines.
   2. Searching for the unit's keyword/name/id.
   3. Falling back to the primary prompt and primary backend file.
   State up front which files you read and why. **If the implementation does not exist yet, say so and stop** — there is nothing to drift-check.

4. **Build the comparison.** For each rule, marker, gate, transition, and conditional in the spec, classify against the code:
   - **Implemented faithfully** — record briefly.
   - **Implemented but drifted** — code does something related but inconsistent (different condition, renamed marker, changed ordering, missing must-have). Quote both sides.
   - **Not implemented** — spec calls for it, code does nothing visible. Quote the spec.
   - **In code but not in spec** — code does something no spec rule calls for. Quote the code, and say whether it looks intentional or like leftover.

5. **Report** in this exact structure, with headings retained even when empty:

   ```
   ## Spec coherence check: <name>

   **Spec read:** <path>
   **Implementation files read:** <list>

   ### Drift found
   1. **<label>.** <Spec quote>. Code <quote>. <Why it matters, one sentence.>

   ### Not implemented
   1. **<label>.** Spec calls for <X>. Not present in files read.

   ### In code but not in spec
   1. **<label>.** Code does <X>. No corresponding spec rule. <Intentional or leftover?>

   ### Implemented faithfully
   - <one-line list of matched rules / markers / gates>

   ### What I didn't check
   - <anything you couldn't reach, flagged as a gap>
   ```

   Sections with no entries print `None.` on a single line. When the unit is specced for a future phase that is not built, collapse the report to a short "Not yet implemented — searched <files> for markers <list>; no matches; re-run after it lands."

## 7. Edge cases and failure handling

- **Ambiguous shorthand:** list matches, ask, stop.
- **No argument:** list available specs, ask, stop.
- **Implementation not built yet:** state which files and markers were searched, mark not-yet-implemented, stop.
- **Large spec** (hundreds to ~1000 lines, or a multi-file bundle): focus on substantive behavior rules; skip surface-level structural prose.
- **Marker present in code but never in spec (or vice versa):** that is a finding, not an error — route it to the right bucket.
- **Cannot locate the file that handles a given marker:** do not guess it is missing — list it under "What I didn't check" as a gap to confirm.

## 8. Guardrails / hard rules

- **Read-only. Never edit specs or code, under any circumstances.**
- **Never run code or start servers.** The check is purely textual.
- **Quote both sides.** Paraphrase alone is not evidence; the user must be able to jump to each quoted line and verify.
- **Concrete findings only.** "The system might not handle X" is not a finding. "Spec line N requires a permission gate before advice; prompt line M delivers advice on the ready signal with no gate" is.
- **Stay in your lane:** behavior, structure, gates, markers. Voice/tone belongs to the separate voice check — record its presence, do not re-audit it.
- **Report, don't patch.** Do not suggest fixes unless asked.

## 9. Acceptance criteria

- Given a valid spec argument with a built implementation, produces the five-section report with at least the spec path and implementation file list populated, and every claimed finding carries a quote from both spec and code.
- Given an ambiguous or absent argument, it lists options and asks rather than guessing.
- Given a spec whose implementation does not exist, it returns the short not-yet-implemented form naming the files and markers it searched — and does not fabricate drift.
- Empty buckets render `None.`, never disappear.
- The run touches nothing: no file is modified, no process is started (verifiable from a clean git status and no spawned servers).
- A planted divergence (rename a marker in code but not the spec) is caught and lands in "Drift found" with both lines quoted.

## 10. Adapt to your setup

- Replace "unit of behavior" with your own **unit** (feature, endpoint, workflow, state machine).
- Point the shorthand resolver at **your** source-of-truth index, and the implementation search at **your** layer layout (prompt / server / frontend, or whatever yours are).
- Swap the marker vocabulary for **your** state-signal convention (named tags, enums, event names, status codes).
- Decide what couples with this skill: if you have a separate **voice/style** or **schema** check, keep the boundary explicit so each owns one concern.
- If your specs are not phase-gated, drop the "not-yet-implemented future-phase" branch.

---

```markdown
---
name: check-spec-coherence
description: Compare a [UNIT] spec against the code that implements it and report drift. Use when the user runs /check-spec-coherence, or asks to check that a [UNIT]'s implementation matches its spec, or to audit whether code drifted from a spec after edits.
---

# Check spec coherence

Read-only. Read a [UNIT] spec, read the code that implements it, report drift. Never edit specs or code; never run anything.

## Argument

A path or shorthand identifying the spec. Resolve shorthand against the [source-of-truth table] in [CLAUDE.md]. If ambiguous, list matches and ask. If absent, list available specs and ask. Do not proceed in either case.

## What to do

### Step 1 — Read the spec
<!-- Extract: behavioral rules, conditionals, gates, required-data (must-have/optional/gating),
     markers and their triggers, transitions, permission gates. Record voice/style blocks but
     defer the judgment to the voice check. -->

### Step 2 — Identify the implementation files
<!-- Search for the spec's markers, then the unit keyword, then fall back to primary prompt +
     backend. State which files you read and why. If not built yet, say so and stop. -->

### Step 3 — Build the comparison
<!-- Classify each rule/marker/gate/transition/conditional: faithful / drifted / not-implemented /
     in-code-not-in-spec. Quote both sides. -->

### Step 4 — Report
<!-- Fixed five-section template: Drift found / Not implemented / In code but not in spec /
     Implemented faithfully / What I didn't check. Empty sections print "None." -->

## Important
<!-- Read-only. No running code. Quote both sides. Concrete findings only. Report, don't patch. -->
```