Initial commit
This commit is contained in:
Zhongwei Li
419
skills/verification-before-completion/SKILL.md
Normal file
419
skills/verification-before-completion/SKILL.md
Normal file
@@ -0,0 +1,419 @@
|
||||
---
|
||||
name: verification-before-completion
|
||||
description: Extended verification including tests AND spec compliance - runs tests, validates spec compliance, checks for drift, blocks completion on failures
|
||||
---
|
||||
|
||||
# Verification Before Completion (Spec-Aware)
|
||||
|
||||
## Overview
|
||||
|
||||
Verify implementation is complete by running tests AND validating spec compliance.
|
||||
|
||||
**Key Additions from Standard Verification:**
|
||||
- Step 1: Run tests (existing behavior)
|
||||
- **Step 2: Validate spec compliance** (new)
|
||||
- **Step 3: Check for spec drift** (new)
|
||||
- Blocks completion if EITHER tests OR spec compliance fails
|
||||
|
||||
## When to Use
|
||||
|
||||
- After implementation and code review
|
||||
- Before claiming work is complete
|
||||
- Before committing/merging/deploying
|
||||
- As final gate in `sdd:implement` workflow
|
||||
|
||||
## The Process
|
||||
|
||||
### 1. Run Tests
|
||||
|
||||
**Execute all tests:**
|
||||
```bash
|
||||
# Run full test suite
|
||||
npm test # or pytest, go test, etc.
|
||||
```
|
||||
|
||||
**Check results:**
|
||||
- All tests passing?
|
||||
- No flaky tests?
|
||||
- Coverage adequate?
|
||||
|
||||
**If tests fail:**
|
||||
- ❌ **STOP - Fix tests before proceeding**
|
||||
- Do not skip this step
|
||||
- Do not claim completion
|
||||
|
||||
### 2. Validate Spec Compliance
|
||||
|
||||
**Load spec:**
|
||||
```bash
|
||||
cat specs/features/[feature-name].md
|
||||
```
|
||||
|
||||
**Check each requirement:**
|
||||
|
||||
```markdown
|
||||
Functional Requirement 1: [From spec]
|
||||
✓ / ✗ Implemented
|
||||
✓ / ✗ Tested
|
||||
✓ / ✗ Matches spec behavior
|
||||
|
||||
Functional Requirement 2: [From spec]
|
||||
...
|
||||
```
|
||||
|
||||
**Verify:**
|
||||
- All requirements implemented
|
||||
- All requirements tested
|
||||
- All behavior matches spec
|
||||
- No missing features
|
||||
- No extra features (or documented)
|
||||
|
||||
**Calculate compliance:**
|
||||
```
|
||||
Spec Compliance: X/X requirements = XX%
|
||||
```
|
||||
|
||||
**If compliance < 100%:**
|
||||
- ❌ **STOP - Use `sdd:evolve` to reconcile**
|
||||
- Document all deviations
|
||||
- Do not proceed until resolved
|
||||
|
||||
### 3. Check for Spec Drift
|
||||
|
||||
**Compare:**
|
||||
- What spec says NOW
|
||||
- What code does NOW
|
||||
- Any divergence?
|
||||
|
||||
**Common drift sources:**
|
||||
- Spec updated but code not
|
||||
- Code changed but spec not
|
||||
- Undocumented additions
|
||||
- Forgotten requirements
|
||||
|
||||
**If drift detected:**
|
||||
- Document each instance
|
||||
- Use `sdd:evolve` to reconcile
|
||||
- Do not proceed with drift
|
||||
|
||||
### 4. Verify Success Criteria
|
||||
|
||||
**From spec, check each criterion:**
|
||||
|
||||
```markdown
|
||||
Success Criteria (from spec):
|
||||
- [ ] Criterion 1: [Description]
|
||||
Status: ✓ Met / ✗ Not met
|
||||
Evidence: [How verified]
|
||||
|
||||
- [ ] Criterion 2: [Description]
|
||||
...
|
||||
```
|
||||
|
||||
**All criteria must be met.**
|
||||
|
||||
If any criterion not met:
|
||||
- ❌ **STOP - Criterion not met**
|
||||
- Implement missing piece
|
||||
- Re-verify
|
||||
|
||||
### 5. Generate Verification Report
|
||||
|
||||
**Report structure:**
|
||||
|
||||
```markdown
|
||||
# Verification Report: [Feature Name]
|
||||
|
||||
**Date:** YYYY-MM-DD
|
||||
**Spec:** specs/features/[feature].md
|
||||
|
||||
## Test Results
|
||||
|
||||
**Status:** ✅ PASS / ❌ FAIL
|
||||
|
||||
```
|
||||
[Test output]
|
||||
```
|
||||
|
||||
**Summary:**
|
||||
- Total: X tests
|
||||
- Passed: X
|
||||
- Failed: X
|
||||
- Coverage: XX%
|
||||
|
||||
## Spec Compliance
|
||||
|
||||
**Status:** ✅ COMPLIANT / ❌ NON-COMPLIANT
|
||||
|
||||
**Compliance Score:** XX%
|
||||
|
||||
### Requirements Status
|
||||
- Functional: X/X (XX%)
|
||||
- Error Cases: X/X (XX%)
|
||||
- Edge Cases: X/X (XX%)
|
||||
- Non-Functional: X/X (XX%)
|
||||
|
||||
### Deviations
|
||||
[List any deviations found]
|
||||
|
||||
## Spec Drift Check
|
||||
|
||||
**Status:** ✅ NO DRIFT / ⚠️ DRIFT DETECTED
|
||||
|
||||
[Details if drift found]
|
||||
|
||||
## Success Criteria
|
||||
|
||||
**Status:** ✅ ALL MET / ❌ INCOMPLETE
|
||||
|
||||
- [✓] Criterion 1
|
||||
- [✓] Criterion 2
|
||||
...
|
||||
|
||||
## Overall Status
|
||||
|
||||
✅ **VERIFIED - Ready for completion**
|
||||
|
||||
OR
|
||||
|
||||
❌ **NOT VERIFIED - Issues must be resolved**
|
||||
|
||||
**Blocking Issues:**
|
||||
- [Issue 1]
|
||||
- [Issue 2]
|
||||
|
||||
**Next Steps:**
|
||||
[What needs to be done]
|
||||
```
|
||||
|
||||
### 6. Make Go/No-Go Decision
|
||||
|
||||
**All conditions must be true:**
|
||||
- [x] All tests passing
|
||||
- [x] Spec compliance 100%
|
||||
- [x] No spec drift
|
||||
- [x] All success criteria met
|
||||
|
||||
**If ALL true:**
|
||||
- ✅ **VERIFIED - Proceed to completion**
|
||||
- Safe to commit/merge/deploy
|
||||
|
||||
**If ANY false:**
|
||||
- ❌ **NOT VERIFIED - Block completion**
|
||||
- Fix issues before proceeding
|
||||
- Re-run verification after fixes
|
||||
|
||||
## Verification Checklist
|
||||
|
||||
Use TodoWrite to track:
|
||||
|
||||
- [ ] Run full test suite
|
||||
- [ ] Verify all tests passing
|
||||
- [ ] Load specification
|
||||
- [ ] Validate spec compliance for all requirements
|
||||
- [ ] Check for spec drift
|
||||
- [ ] Verify all success criteria met
|
||||
- [ ] Generate verification report
|
||||
- [ ] Make go/no-go decision
|
||||
- [ ] If not verified: Document blocking issues
|
||||
- [ ] If verified: Proceed to completion
|
||||
|
||||
## Example: Verification PASS
|
||||
|
||||
```
|
||||
You: Running verification before completion...
|
||||
|
||||
Step 1: Running tests...
|
||||
|
||||
$ npm test
|
||||
|
||||
✅ All tests passing (24/24)
|
||||
✅ Coverage: 95%
|
||||
|
||||
Step 2: Validating spec compliance...
|
||||
|
||||
Reading spec: specs/features/user-profile-api.md
|
||||
|
||||
Checking requirements:
|
||||
✓ Functional Requirement 1: PUT endpoint - Implemented & tested
|
||||
✓ Functional Requirement 2: Validation - Implemented & tested
|
||||
✓ Functional Requirement 3: Auth - Implemented & tested
|
||||
✓ Functional Requirement 4: Authorization - Implemented & tested
|
||||
✓ Functional Requirement 5: Response format - Implemented & tested
|
||||
✓ Functional Requirement 6: Partial updates - Implemented & tested
|
||||
|
||||
✓ Error Case 1: Missing JWT - Handled & tested
|
||||
✓ Error Case 2: User not found - Handled & tested
|
||||
✓ Error Case 3: Validation failure - Handled & tested
|
||||
✓ Error Case 4: Authorization failure - Handled & tested
|
||||
|
||||
✓ Edge Case 1: Empty update - Handled & tested
|
||||
✓ Edge Case 2: Invalid avatar URL - Handled & tested
|
||||
✓ Edge Case 3: Special characters in name - Handled & tested
|
||||
|
||||
Spec Compliance: 13/13 = 100% ✅
|
||||
|
||||
Step 3: Checking for spec drift...
|
||||
|
||||
Comparing spec to implementation...
|
||||
No drift detected ✅
|
||||
|
||||
Step 4: Verifying success criteria...
|
||||
|
||||
From spec:
|
||||
✓ Authenticated users can update their profile
|
||||
✓ Validation errors return 422 with clear messages
|
||||
✓ Users cannot update other users' profiles
|
||||
✓ All edge cases handled gracefully
|
||||
|
||||
All criteria met ✅
|
||||
|
||||
=== VERIFICATION REPORT ===
|
||||
|
||||
✅ Tests: PASS (24/24)
|
||||
✅ Spec Compliance: 100%
|
||||
✅ Spec Drift: None
|
||||
✅ Success Criteria: All met
|
||||
|
||||
**OVERALL: ✅ VERIFIED**
|
||||
|
||||
Implementation is complete and verified. Ready for commit/merge.
|
||||
```
|
||||
|
||||
## Example: Verification FAIL
|
||||
|
||||
```
|
||||
You: Running verification before completion...
|
||||
|
||||
Step 1: Running tests...
|
||||
|
||||
$ npm test
|
||||
|
||||
❌ Tests FAILED (22/24 passing, 2 failing)
|
||||
|
||||
Failures:
|
||||
1. "Should handle database connection errors"
|
||||
Error: Connection retry not implemented
|
||||
|
||||
2. "Should return 503 when database unavailable"
|
||||
Error: Returns 500 instead of 503
|
||||
|
||||
**BLOCKING: Tests must pass before proceeding**
|
||||
|
||||
Step 2: Validating spec compliance...
|
||||
|
||||
Reading spec: specs/features/user-profile-api.md
|
||||
|
||||
Checking requirements:
|
||||
[checks requirements...]
|
||||
|
||||
❌ Non-Functional Requirement 1: Database retry logic
|
||||
Status: Not implemented
|
||||
Spec says: "3 retry attempts with exponential backoff"
|
||||
Code does: Single attempt, no retry
|
||||
|
||||
Spec Compliance: 12/13 = 92% ❌
|
||||
|
||||
Step 3: Checking success criteria...
|
||||
|
||||
From spec:
|
||||
✓ Authenticated users can update their profile
|
||||
✓ Validation errors return 422
|
||||
✗ Handles database failures gracefully (missing retry logic)
|
||||
✓ Users cannot update other users' profiles
|
||||
|
||||
=== VERIFICATION REPORT ===
|
||||
|
||||
❌ Tests: FAIL (2 failures)
|
||||
❌ Spec Compliance: 92% (missing retry logic)
|
||||
❌ Success Criteria: 3/4 met
|
||||
|
||||
**OVERALL: ❌ NOT VERIFIED**
|
||||
|
||||
**Blocking Issues:**
|
||||
1. Database retry logic not implemented (from spec)
|
||||
2. Tests failing for error handling
|
||||
3. Returns wrong HTTP status (500 vs 503)
|
||||
|
||||
**Next Steps:**
|
||||
1. Implement database retry logic per spec
|
||||
2. Fix HTTP status code
|
||||
3. Re-run verification
|
||||
|
||||
**DO NOT PROCEED until all issues resolved.**
|
||||
```
|
||||
|
||||
## Common Failure Scenarios
|
||||
|
||||
### Scenario: Tests Pass but Spec Compliance Fails
|
||||
|
||||
```
|
||||
✅ Tests: 24/24 passing
|
||||
❌ Spec Compliance: 85%
|
||||
❌ BLOCKED
|
||||
|
||||
Issue: Tests don't cover all spec requirements
|
||||
|
||||
Action: Add tests for uncovered requirements, re-verify
|
||||
```
|
||||
|
||||
### Scenario: Spec Compliant but Tests Fail
|
||||
|
||||
```
|
||||
❌ Tests: 20/24 passing
|
||||
✅ Spec Compliance: 100%
|
||||
❌ BLOCKED
|
||||
|
||||
Issue: Implementation exists but has bugs
|
||||
|
||||
Action: Fix bugs, ensure tests pass, re-verify
|
||||
```
|
||||
|
||||
### Scenario: Both Pass but Drift Detected
|
||||
|
||||
```
|
||||
✅ Tests: 24/24 passing
|
||||
✅ Spec Compliance: 100%
|
||||
⚠️ Spec Drift: Spec updated after implementation
|
||||
❌ BLOCKED
|
||||
|
||||
Issue: Spec changed, code doesn't reflect changes
|
||||
|
||||
Action: Update code or revert spec, re-verify
|
||||
```
|
||||
|
||||
## Quality Gates
|
||||
|
||||
**This skill enforces quality gates:**
|
||||
|
||||
1. **All tests must pass** (from superpowers)
|
||||
2. **100% spec compliance required** (new)
|
||||
3. **No spec drift allowed** (new)
|
||||
4. **All success criteria must be met** (new)
|
||||
|
||||
**No exceptions. No shortcuts.**
|
||||
|
||||
These gates exist to prevent:
|
||||
- Incomplete implementations
|
||||
- Untested code
|
||||
- Spec/code divergence
|
||||
- False claims of completion
|
||||
|
||||
## Remember
|
||||
|
||||
**Verification is not optional.**
|
||||
|
||||
- Don't skip verification "just this once"
|
||||
- Don't claim completion without verification
|
||||
- Don't ignore failing gates
|
||||
|
||||
**Verification failures are information.**
|
||||
|
||||
- Tests failing? Code has bugs
|
||||
- Spec compliance failing? Missing features
|
||||
- Drift detected? Synchronization problem
|
||||
- Criteria not met? Work incomplete
|
||||
|
||||
**Fix issues, don't rationalize past them.**
|
||||
|
||||
**Evidence before assertions. Always.**
|
||||
Reference in New Issue
Block a user