Spec Vs Impl Checker

Spec-vs-Implementation Checker

Systematically verify that every specification requirement is implemented correctly.

Process

Step 1 — Build Requirement Registry

Extract every requirement from the spec and combined plan into a structured registry:

| Req ID | Source | Section | Requirement | Type |
|---|---|---|---|---|
| REQ-001 | spec.md | 4.1 | Users can register with email/password | Functional |
| REQ-002 | spec.md | 4.1 | Email must be validated (format + uniqueness) | Validation |
| REQ-003 | combined-plan.md | 2 | Passwords hashed with bcrypt (cost 12) | Security |
| REQ-004 | architecture.md | 3.2 | Auth module exposes /api/auth/* endpoints | Interface |

Step 2 — Trace to Implementation

For each requirement, find the implementing code:

| Req ID | Implementation | File(s) | Test(s) | Status |
|---|---|---|---|---|
| REQ-001 | register() handler | src/auth/handlers.rs:45 | test_register | VERIFIED |
| REQ-002 | validate_email() | src/auth/validation.rs:12 | test_email_validation | VERIFIED |
| REQ-003 | hash_password() | src/auth/crypto.rs:8 | — | UNTESTED |
| REQ-004 | router config | src/auth/mod.rs:20 | test_auth_routes | VERIFIED |

Step 3 — Verify Each Requirement

For each traced requirement:

1. Read the code — Does the implementation match what the spec describes?
2. Check the tests — Is there a test that verifies this specific requirement?
3. Run the test — Does the test actually pass?
4. Check edge cases — Does the implementation handle the edge cases the spec implies?

Status values:

| Status | Meaning | |---|---| | VERIFIED | Implemented correctly, tested, test passes | | IMPLEMENTED | Code exists but no specific test | | UNTESTED | Code exists, test exists but doesn't cover this requirement | | PARTIAL | Partially implemented (e.g., happy path only, missing error handling) | | MISSING | No implementation found for this requirement | | DEVIATED | Implementation differs from spec (document how) |

Step 4 — Interface Contract Verification

For each module interface defined in the architecture:

• Verify the interface exists as specified (endpoints, function signatures, types)
• Verify error contracts (what errors can be returned, in what format)
• Verify data contracts (request/response shapes match the architecture doc)
• Test cross-module integration points

Step 5 — Generate Traceability Report

# Spec-vs-Implementation Report — 

**Date:** YYYY-MM-DD
**Spec Requirements:** N
**Verified:** X (Y%)
**Partial/Missing:** Z

## Requirement Traceability Matrix

[Full table from steps 1-3]

## Interface Contract Status

[Table of module interfaces and their verification status]

## Gaps Found

### Missing Implementations
- REQ-XXX: [description, severity]

### Deviations from Spec
- REQ-YYY: Spec says [X], implementation does [Y]. Impact: [assessment]

### Untested Requirements
- REQ-ZZZ: Implemented but no test coverage

When to Escalate

• Missing implementation → Bug report to Forge
• Spec ambiguity → Flag to Clawpick for Sage/Prism clarification
• Architecture deviation → Flag to Arc
• Security constraint not met → Flag to Zero

---

Watchdog skill — Spec-vs-implementation traceability and verification

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Firstp1ck
• Source: Firstp1ck/pi-coding-agent-forge
• License: MIT

Install and usage instructions live in the source repository linked above.