| name | sdd-verification |
| description | SDD acceptance criteria verification — maps specification acceptance criteria to tests, validates implementation output against spec requirements, and produces artifact-pyramid-compliant VERIFICATION.md reports. Trigger when implementation needs to be verified against its specification. |
| version | 1.0.0 |
| author | Hermes Agent community |
| license | MIT |
| metadata | {"hermes":{"tags":["sdd","verification","acceptance-criteria","testing","compliance","quality"],"related_skills":["sdd-authoring","sdd-work-decomposition","sdd-review"]}} |
SDD Verification
Validating that implementation output satisfies every acceptance criterion defined in the specification. This skill owns the Verify phase of the SDD pipeline — the final gate before delivery.
SDD Pipeline Position
SPECIFY → PLAN → TASKS → IMPLEMENT → [VERIFY]
↑
You are here
Verification is the phase that closes the loop. If specification is the question ("what should the system do?") and implementation is the answer ("this is what the system does"), verification is the judgment ("does the answer satisfy the question?").
Core Principle: Every AC Produces a Binary Verdict
An acceptance criterion that cannot produce a CLEAR PASS or CLEAR FAIL is not a well-defined AC. Verification exposes spec defects: if a criterion is ambiguous and cannot be tested, it is a spec bug, not an implementation failure. Verification findings thus flow in two directions — implementation failures (code doesn't meet the spec) and spec failures (the spec is untestable or ambiguous).
Artifact-Pyramid Output: VERIFICATION.md
Verification reports follow the artifact-pyramid structure:
| Layer | Content | File |
|---|
| L1 | Pass/fail summary — total ACs tested, pass count, fail count, compliance score, blocking verdict | 00-index.md (entry point) |
| L2 | Verification matrix — per-story or per-feature-area AC status grouped for navigation | Individual *.verification.md files |
| L3 | Individual failure dossiers — what failed, expected behavior (from spec), actual behavior (from implementation), evidence, severity | dossiers/ directory |
| SOURCES | Cross-reference from each AC back to its SPEC.md section | Footer of each file |
Loading Guidance
| Reference | When to load | File |
|---|
| Acceptance Criteria Verification | Before running verification — methodology for testing ACs that may not have dedicated test infrastructure | references/acceptance-criteria-verification.md |
| Spec-to-Test Mapping | When existing tests exist — how to map test coverage back to spec ACs and identify gaps | references/spec-to-test-mapping.md |
| Escalation Protocol | When an AC is ambiguous or an implementation finding needs escalation — what to do when verification can't produce a clean verdict | references/escalation-protocol.md |
| Template | When to use | File |
|---|
| VERIFICATION.md | Producing a verification report after implementation | templates/VERIFICATION.md |
| Script | When to run | File |
|---|
verification-report.sh | After verification — generates the AC pass/fail matrix from structured input | scripts/verification-report.sh |
Trigger Conditions
Invoke this skill when:
- An implementation agent has completed its task and claims acceptance criteria are met
- A PR or MR needs spec-compliance verification before merge
- A spec amendment needs to be verified against existing test coverage
- An integration test suite needs mapping back to the specification's acceptance criteria
Verification Dimensions
Functional Correctness
Does the implementation produce the correct output for each specified input? Test against all normal cases, edge cases, and error conditions from the spec.
Behavioral Completeness
Does the implementation handle every scenario the spec describes? An implementation that handles all normal cases but crashes on a documented edge case is functionally correct for some inputs but behaviorally incomplete.
Contract Compliance
Does the implementation honor the data contracts, interface signatures, and protocol definitions from the spec? A function that returns the right value with the wrong type or shape is not compliant.
Non-Functional Requirements
Does the implementation meet the performance, security, observability, and compliance requirements from the spec? An NFR failure may not produce wrong output but may produce unacceptable behavior in production.
Negative Testing
Does the implementation correctly reject invalid inputs per the spec? A system that accepts what it should reject is a security and correctness risk, even if it handles valid inputs perfectly.
Severity Classification
| Severity | Definition | Disposition |
|---|
| BLOCKING | An AC is failed and no workaround exists — the system does not meet a core requirement | Gate does not pass |
| CRITICAL | An AC is failed but a feasible workaround exists | Gate does not pass without documented exception |
| MINOR | An AC passes but with suboptimal behavior, or a non-functional requirement is partially met | Gate can pass with remediation plan |
| INFO | An observation that does not affect pass/fail status — spec improvement suggestion, test gap | Informational |
Gate Verdict Calculation
After classifying each AC by severity, produce a single gate verdict that determines whether the implementation passes to the next SDD phase. The verdict is computed deterministically from severity counts:
| Condition | Verdict |
|---|
| 0 BLOCKING, 0 CRITICAL, all ACs tested | APPROVED — the implementation satisfies the specification |
| 0 BLOCKING, ≤2 CRITICAL with remediation plans documented | CONDITIONS — implementation passes but requires tracked remediation of CRITICAL failures |
| Any BLOCKING failure | REJECTED — core requirement unmet; remediation must be completed and re-verified |
| ≥3 CRITICAL failures without documented remediation plans | REJECTED — unacceptable failure density without resolution path |
| < 90% compliance score without documented exception | REJECTED — overall quality below threshold |
The Gate Verdict MUST be included in the L1 summary of every VERIFICATION.md. This makes the verification output directly consumable by the downstream sdd-review phase gate.
Remediation Recommendation Format
Each BLOCKING, CRITICAL, and MINOR finding in the L3 dossiers SHOULD include a remediation recommendation following this structure:
- What to fix: The specific code, config, or behavior that needs to change
- Why this severity: The impact that justifies the severity classification
- Verification for the fix: How to confirm the fix satisfies the AC (specific test or check)
Remediation recommendations are guidance for the implementation agent — they are NOT spec amendments. If the remediation suggests a spec change (ambiguous AC, missing AC), escalate per the Escalation Protocol instead.
