Verify against spec

Verify Against Spec

Parallel verification that catches implementation gaps before they slip through context compaction.

When to Use

• End of a multi-session feature development cycle
• "Make sure we haven't missed anything"
• Context window is filling up and you want a coverage check
• After a code review that introduced fixes — are all fixes applied?

Do NOT use for: Simple single-file changes, bug fixes without a spec, UI polish.

Process

Find spec file (+ design contract, if one exists)
    │
    ▼
Launch parallel agents
    ├─► Spec Coverage Verifier
    ├─► Build + Test
    ├─► Docs Sync
    └─► Visual Fidelity Verifier   (only when a design-contract + captures/ exist)
    │
    ▼
Triage results
    │
    ▼
High severity gaps? ─► Yes ─► Fix gaps ─► Commit
                    └► No  ─► Commit

Checkpoint Compaction

Before launching verification agents, after aggregating their findings, and before fixing any high-severity gaps, update the spec plan or verification report with a durable checkpoint. Include completed work, remaining steps, changed files, decisions made, verification already run, failures, and the next exact command. After compaction or a new session, re-read the checkpoint and git status before continuing. This skill exists partly because context compaction hides gaps; never compact before the verification findings have been written down.

Step 1: Find the Spec

Look in order:

1. docs/plans/<feature-plan>.md
2. docs/brainstorm/<feature>/design.md
3. Ask the user if unclear

Also look for a design contract (<app>/docs/vision/<feature>-design-contract.md, see design-contract). If one exists with a captures/ directory, enable Agent 4.

Step 2: Launch Parallel Agents

Dispatch the agents simultaneously. Each runs independently. Agent 4 runs only when a design contract + captures exist (UI-fidelity work); skip it for non-visual features.

Coordinator (you)
├─► Agent 1 — Spec Coverage Verifier   [Standard tier: claude-sonnet-4-6 / gpt-4.1 / gemini-3.1-pro / kimi-k2.5]
├─► Agent 2 — Build + Test             [Fast tier:     claude-haiku-4-5 / gpt-4.1-mini / gemini-3.0-flash / kimi-for-coding]
├─► Agent 3 — Docs Sync               [Fast tier:     claude-haiku-4-5 / gpt-4.1-mini / gemini-3.0-flash / kimi-for-coding]
└─► Agent 4 — Visual Fidelity Verifier [Standard tier: claude-sonnet-4-6 / gpt-4.1 / gemini-3.1-pro / kimi-k2.5]   (conditional)
         │
         ▼ (all complete)
Coordinator — triage and fix

Agent 1 — Spec Coverage Verifier

Prompt template:

You are verifying implementation coverage for a feature.

DESIGN SPEC: <path to spec or plan>

Read the spec and identify every requirement, behavior, and component it describes.
Then read the implementation files listed below.

For each spec requirement, determine:
- IMPLEMENTED: clearly present in code
- PARTIAL: partially implemented or different from spec
- MISSING: not found in implementation

Implementation files to check:
<list the key new/modified files from this feature>

Return a list sorted by severity (High = functional gap, Medium = behavioral mismatch, Low = cosmetic/naming).
Format each gap as: [Severity] Requirement | Current State | Spec Says

Agent 2 — Build + Test

(Fast tier — mechanical execution, no judgment required)

Run your project's build and test commands:

# Build — use your project's build system
# Examples: xcodebuild, swift build, make build
<project-build-command> 2>&1 | grep -E "error:|BUILD SUCCEEDED|BUILD FAILED"

# Test — use your project's test runner
<project-test-command> 2>&1 | tail -5

Report: build status + test count + any failures.

Agent 3 — Docs Sync

(Fast tier — read-only comparison)

Check:

• Project documentation — do conventions accurately reflect new patterns introduced?
• Memory files — do they capture key decisions/gotchas from this session?
• Plan file — should it be moved to a completed folder?

Return: list of stale/missing entries with suggested updates.

Agent 4 — Visual Fidelity Verifier (conditional)

(Standard tier — judgment required. Run only when a design-contract + captures/ exist.)

Where Agent 1 checks behavioral coverage, this agent checks visual coverage against the design contract's §9 canonical frames. It does not eyeball "close enough" — it checks contracted tokens and the presence of capture proof.

Prompt template:

You are verifying visual fidelity for a UI feature against its design contract.

DESIGN CONTRACT: <app>/docs/vision/<feature>-design-contract.md
CAPTURES DIR:    <app>/docs/vision/captures/
IMPLEMENTATION:  <list the SwiftUI view files changed in this feature>

For each canonical frame in the contract's §9 table:
- CAPTURE PRESENT: is there a captures/<PreviewName>.png matching the §9 Preview name?
- PREVIEW EXISTS:  does a #Preview with that exact name exist in the view files?
For the implementation, check the contract's hard tokens:
- §1 colors:   any raw hex literal in view code instead of a named token? (violation)
- §2 type:     font sizes match the SwiftUI-mapping column (not the mockup px)?
- §8 copy:     every user-facing string matches §8 VERBATIM, by string id (punctuation included)?
- §10 rules:   any non-negotiable violated (e.g. count-down where count-up is required, light mode, new screen)?

Return a list sorted by severity:
  High   = §10 non-negotiable violated, or a contracted frame has neither preview nor capture
  Medium = token/typography/copy mismatch vs the contract
  Low    = capture missing but preview exists (needs a render, not a code change)
Format each: [Severity] §section | Current State | Contract Says

If captures are pending a human render (machine could not render — see preview-capture Step 3), that is a Low, not a High: flag "capture pending" rather than failing the gate, since the preview compiling under the archive build is the available proof.

Step 3: Triage and Fix

Severity	Action
High	Fix before committing — functional gap
Medium	Fix if quick (<15 min), otherwise file a note
Low	Skip — cosmetic, not worth the churn

Fix High gaps by re-reading the relevant spec section and comparing to the implementation. Don't invent new behavior — follow the spec.

Step 4: Commit

After fixes:

git add -p
git commit -m "fix(feature): address spec coverage gaps from verification"

Common Gaps Found

Based on experience with Apple platform projects:

• Sheet environment injection: New sheets often miss @Environment props that parent views have
• Empty state handling: Spec says show message X, implementation shows nothing
• Toast/confirmation feedback: Spec says "show toast after action", action is silent
• Dead code leftover: Old implementations not deleted when replaced
• Filter/state cleanup: ViewModel has unused state from previous design

Example

Verifying a "Saved Filters" feature against its design spec:

/verify-against-spec docs/plans/saved-filters.md

The three agents run in parallel and report back. A typical triage looks like:

Spec Coverage Verifier
  ✅ Filter persistence (SwiftData)         — FiltersStore.swift:42
  ✅ Apply filter from list                 — FilterListView.swift:88
  ❌ Spec §3.2 "edit a saved filter"        — NO matching view/action found
  ⚠️  Spec §4.1 empty state copy            — shows blank list, spec wants a message

Build + Test            ✅ Build clean, 41/41 unit tests pass
Docs Sync               ⚠️  README still describes the old single-filter behavior
Visual Fidelity         ✅ F1–F5 captures present and named
                        ⚠️  §8 copy: button reads "Save filter" — contract says "Save"
                        ❌ §10: list uses count-down badge — contract requires count-up

Triage outcome: implement the missing edit flow (§3.2 — blocking), fix the count-up violation (§10 — blocking), correct the button copy (§8), add the empty-state message (§4.1), update the README, then re-run before committing.

Quick Reference

/verify-against-spec docs/plans/feature-redesign.md
/verify-against-spec docs/brainstorm/2026-03-20-new-feature/design.md

Run at the end of every multi-day feature branch. Context compaction hides gaps — this surfaces them.

Relationship to Other Skills

Skill	When	Purpose
verify-against-spec	End of spec-driven work	Coverage vs design spec (+ visual fidelity)
design-contract	Before building a mockup	Authors the contract + §9 frames this skill verifies against
preview-capture	Producing capture proof	Renders the §9 #Previews into captures/ that Agent 4 checks
complete-feature	Feature feels done	Comprehensive checklist
merge-check	Before merging to main	Pre-merge quality gate
regression-test	During bug fix	TDD-first regression workflow