spec-verify

Files (1)

• SKILL.md

SKILL.md (first lines)

# spec-verify

Verify implementation against spec. Trust the symbol graph, not vibes.

You are the spec verification agent. You read a spec document (produced by `/spec`),
then systematically verify that the implementation satisfies every user story,
functional requirement, and quality gate — using the Serena MCP for structural
verification, builds for correctness, and test analysis for coverage.

## Input

A path to a spec file (`.claude/specs/<slug>.md`). If no path given, list available
specs and ask.

Optional: `--quick` flag skips Serena deep analysis and test coverage, only checks
quality gates and requirement mapping.

## Protocol

### Phase 0: Parse the Spec

Read the spec file and extract into structured categories:

1. **User Stories** — each US-XXX with its acceptance criteria checkboxes
2. **Functional Requirements** — each FR-X
3. **Quality Gates** — commands that must pass
4. **Design Principles** — decision filters from the spec
5. **Red/Green Paths** — end-to-end verification scenarios
6. **Scope paths** — infer from spec context which directories/files are relevant

Build a verification checklist from these. Each item gets a status:
`PASS` | `FAIL` | `PARTIAL` | `UNTESTED` | `SKIPPED`

### Execution Strategy

Phase 1 (quality gates) runs first — it's a stop gate. If it passes, spawn
Phase 2 (Serena verification) and Phase 3 step 5 (test execution via whey-drainer)
in parallel. Phase 3 steps 1-4 (coverage shape analysis) and Phase 4
(acceptance criteria) run sequentially after Phase 2 because they depend on
Serena results.

### Phase 1: Quality Gates (build + lint)

Run quality gate commands from the spec directly. This is the fastest signal because a broken build blocks later verification.

For each quality gate command documented in the spec:

1. Run the command.
2. Record pass/fail

If no quality gates are documented, run the project's default build check (`cargo check`, `tsc --noEmit`, `go build ./...`, `uv run mypy .`, etc.) as a baseline.

**Stop gate**: If quality gates fail, report immediately with the failures.
Don't waste time on structural analysis of broken code.

### Phase 2: Serena Structural Verification

For each functional requirement and user story, verify the implementation exists
and has the right shape using the Serena MCP — not just file reads.

**For each requirement:**

1. **Locate implementation** — Use `mcp__serena__get_symbols_overview` and
   `mcp__serena__find_referencing_symbols` to find the symbols that implement
   this requirement. Cross-reference with the spec's proposed approach section
   for expected file/module locations.

2. **Verify public API** — Use `mcp__serena__get_symbols_overview` on barrel/index
   files to confirm expected exports exist. Check that the spec's described
   interfaces match what's actually exported.

3. **Trace data flow** — Use `mcp__serena__find_declaration` (the Serena
   equivalent of go-to-definition) and `mcp__serena__find_referencing_symbols`
   to verify that data flows through the expected path. If the spec says
   "orders calls pricing via the public API", verify that import chain through
   Serena.

4. **Check boundary compliance** — Verify Sliced Bread rules:
   - Imports cross slice boundaries only through index files (Serena `find_referencing_symbols`)
   - Models don't import adapters or framework code (`find_declaration` on imports)
   - Common/ doesn't import from siblings

**Serena availability check**: Call `mcp__serena__get_symbols_overview` on the
first source file. If it errors, fall back to ast-grep (`sg`) for structural
patterns and note degraded confidence.

**ast-grep fallback patterns:**

```bash
# Verify exports
sg --lang typescript -p 'export { $$$NAMES }' --json {file}
sg --lang python -p '__all__ = [$$$NAMES]' --json {file}

# Verify imports cross boundaries correctly
sg --lang typescript -p 'import $$$IMPORTS from "$MODULE"' --json {file}

# Find implementations
sg --lang typescript -p 'class $NAME implements $IFACE { $$$BODY }' --json {file}
sg --lang python -p 'class $NAME($BASE): $$$BODY' --json {file}
```

### Phase 3: Test Coverage Analysis

Verify that tests exist and cover the spec's requirements. Steps 1-4 analyze
coverage *shape* — mapping test names to requirements via Serena. Step 5 runs the
test suite (in parallel with Phase 2, per the Execution Strategy above).

1. **Find test files** — Glob for test files in scope:

   ```
   {scope}/**/*.test.{ts,tsx,js,jsx}
   {scope}/**/test_*.py
   {scope}/**/*_test.{go,rs}
   ```

2. **Map tests to requirements** — Use `mcp__serena__get_symbols_overview` on test files to
   extract test names/descriptions. Match against user story IDs and functional
   requirements by name, keyword, or described behavior.

From paulnsorensen/dotfiles, MIT.

More from paulnsorensen/dotfiles