Compares specification documents against implementation code to find divergences. Use when implementation of a spec or design doc is claimed complete.

vibe-spec-vs-code-audit

Name: vibe-spec-vs-code-audit
Author: mracal

Specs drift from code. Code drifts from specs. This skill catches the gaps.

When to Use This Skill

Implementation of a spec/design doc is claimed complete
After a major refactor that should still conform to a spec
During periodic compliance checks
When debugging unexpected behavior (maybe the code doesn't match the spec)

When NOT to Use This Skill

No spec or design doc exists (nothing to compare against)
The spec is explicitly marked as aspirational/future
Code was intentionally diverged with documented reasons

Steps

Identify the spec — Find the specification document (design doc, PRD section, API spec, etc.)
Identify the implementation — Find the code files that implement this spec
Line-by-line comparison — For each requirement/section in the spec:
- Find the corresponding code
- Check: Does the code match the spec exactly?
- If divergent: Record as a GAP
Classify each gap:
- ID: GAP-[section]-[number] (e.g., GAP-AUTH-001)
- Type: Missing (spec says X, code has nothing) / Incorrect (spec says X, code does Y) / Extra (code has X, spec doesn't mention it)
- Severity: Critical (breaks core functionality) / High (wrong behavior) / Medium (incomplete) / Low (cosmetic)
Report:

Output Format

Spec vs Code Audit

Spec: [document name/path] Implementation: [code path(s)] Gaps Found: X (Y critical, Z high)

GAP ID	Type	Severity	Spec Says	Code Does
GAP-AUTH-001	Missing	Critical	"Tokens expire after 24h"	No expiration logic found

Top 3 Risks

[Most dangerous gap]

Recommended Fix Order

[Fix critical gaps first]