Validation Workflow
Prove your code works before shipping.
Overview
The Validation Command
/specweave:validate 0001
This runs comprehensive checks on your increment.
What Gets Validated
1. Task Completion
✓ Tasks: 15/15 complete (100%)
All tasks in tasks.md must be marked complete.
If failing:
/specweave:progress 0001
# See which tasks are incomplete
2. Test Suite
✓ Tests: 47/47 passing
All automated tests must pass.
If failing:
npm test
# See which tests fail
3. Code Coverage
✓ Coverage: 87% (target: 80%)
Coverage must meet threshold defined in plan.md.
If failing:
npm run test:coverage
# See which lines are uncovered
4. Acceptance Criteria
✓ AC-IDs: 12/12 satisfied
✓ AC-US1-01: User can register
✓ AC-US1-02: Email must be unique
...
Every AC-ID in spec.md must be validated.
If failing:
- Review spec.md for uncovered ACs
- Add tests or implementation for missing ACs
5. Quality Gates
✓ Lint: 0 errors
✓ Types: No TypeScript errors
✓ Format: All files formatted
Code quality checks must pass.
If failing:
npm run lint
npm run typecheck
npm run format
Validation Levels
Quick Validation
/specweave:validate 0001 --quick
- Task completion
- Test pass/fail
- Basic lint check
Full Validation
/specweave:validate 0001
- All quick checks
- Coverage threshold
- AC-ID tracing
- Documentation completeness
AI Quality Assessment
/specweave:qa 0001
- All validation checks
- AI review of code quality
- Risk assessment
- Improvement suggestions
The Validation Report
# Increment Validation: 0001-user-authentication
## Summary
Status: READY TO SHIP
## Checks
### Tasks
- Total: 15
- Complete: 15
- Status: PASS
### Tests
- Total: 47
- Passing: 47
- Failing: 0
- Status: PASS
### Coverage
- Target: 80%
- Actual: 87%
- Status: PASS
### Acceptance Criteria
- Total AC-IDs: 12
- Satisfied: 12
- Missing: 0
- Status: PASS
### Quality
- Lint errors: 0
- Type errors: 0
- Format issues: 0
- Status: PASS
## Conclusion
All validation gates passed. Ready for /specweave:done.
Common Validation Issues
Issue: Tests Failing
✗ Tests: 45/47 passing
Failed:
- auth.test.ts: should reject expired token
- user.test.ts: should require email verification
Fix:
- Run tests locally:
npm test - Debug failing tests
- Fix implementation or test
- Re-validate
Issue: Coverage Below Threshold
✗ Coverage: 72% (target: 80%)
Uncovered:
- src/utils/helpers.ts: lines 45-67
- src/services/email.ts: lines 12-30
Fix:
- Identify uncovered code
- Add missing tests
- Consider if code is dead (remove it)
- Re-validate
Issue: AC Not Satisfied
✗ AC-IDs: 11/12 satisfied
Missing:
- AC-US3-02: User can reset password via email
Fix:
- Check if feature is implemented
- Add tests proving AC is met
- Link tests to AC-ID in tasks.md
- Re-validate
Issue: Lint Errors
✗ Lint: 3 errors
Errors:
- src/auth.ts:45 - 'unused' is defined but never used
- src/user.ts:23 - Unexpected any
- src/api.ts:67 - Missing return type
Fix:
npm run lint:fix
# Or fix manually
Pre-Validation Checklist
Before running validation:
- All tasks marked complete in tasks.md
- All tests passing locally
- No console.log statements in production code
- Error handling is complete
- Edge cases are covered
- Documentation is updated
Validation in CI/CD
Integrate validation into your pipeline:
# .github/workflows/validate.yml
name: Increment Validation
on:
pull_request:
branches: [main, develop]
jobs:
validate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Setup Node
uses: actions/setup-node@v4
with:
node-version: '20'
- name: Install
run: npm ci
- name: Lint
run: npm run lint
- name: Type Check
run: npm run typecheck
- name: Test
run: npm test
- name: Coverage
run: npm run test:coverage
env:
COVERAGE_THRESHOLD: 80
After Validation Passes
# All checks passed? Close the increment
/specweave:done 0001
This:
- Marks increment as complete
- Updates living docs
- Syncs to external tools (GitHub/JIRA)
- Archives increment data