Validate Plan

Validate Skill

Comprehensive validation of implemented features against their technical specifications. Ensures code quality, test coverage, and spec compliance before final merge.

Prerequisites

• Completed orchestration: Feature implementation finished via /skill:swarm
• Feature branch: Code exists in feat/{feature-name} branch
• Spec file: docs/specs/{feature-name}-spec.md exists
• Test infrastructure: Testing tools configured (Vitest, Playwright, etc.)

Usage

/skill:validate <feature-name>                    # Full validation suite
/skill:validate <feature-name> --tests-only       # Run tests only, skip spec alignment
/skill:validate <feature-name> --spec-only        # Check spec alignment only, skip tests  
/skill:validate <feature-name> --coverage-only    # Check test coverage only
/skill:validate <feature-name> --fix              # Auto-fix issues where possible

Workflow

Phase 1: Environment Setup

1. Switch to feature branch feat/{feature-name}
2. Ensure clean working directory
3. Install/update dependencies
4. Verify test infrastructure is working

Phase 2: Spec Alignment Analysis

1. Load Context

   • Read spec from docs/specs/{feature-name}-spec.md
   • Extract acceptance criteria, API contracts, data models
   • Identify all required components and behaviors

2. Code Analysis

   • Scan implemented code in feature branch
   • Map implemented components to spec requirements
   • Identify API endpoints, data models, business logic
   • Check for security considerations from spec

3. Alignment Verification

   • All API endpoints match spec contracts
   • Data models align with spec definitions
   • Business logic implements all requirements
   • Security measures implemented as specified
   • Performance considerations addressed
   • Error handling matches spec

4. Generate Alignment Report

   • ✅ Implemented correctly
   • ⚠️ Partial implementation or deviations
   • ❌ Missing or incorrect implementation
   • 📝 Recommendations for fixes

Phase 3: Test Execution

1. Unit Tests

   • Run: npm test or equivalent
   • Check coverage: Minimum 80% required
   • Validate: All business logic, utilities, pure functions tested

2. Integration Tests (for non-UI components)

   • Run API endpoint tests
   • Test database operations
   • Test external service integrations
   • Verify authentication/authorization flows
   • Test error handling scenarios

3. End-to-End Tests

   • Run critical user path tests
   • Test complete feature workflows
   • Verify UI components (if applicable)

4. Coverage Analysis

   # Generate detailed coverage report
   npm run test:coverage
   # Check coverage thresholds
   # Report on areas lacking coverage
   

Phase 4: Quality Gates

Validate against these criteria:

Code Quality

• Unit test coverage ≥ 80%
• Integration tests present for all non-UI components
• E2E tests cover critical paths
• No test failures
• Code follows established patterns
• Security vulnerabilities addressed

Spec Compliance

• All acceptance criteria met
• API contracts implemented correctly
• Data models match specification
• Performance targets achieved (if specified)
• Error handling as documented
• Security requirements implemented

Documentation

• Code comments where needed
• README updates (if required)
• API documentation (if applicable)
• Migration guides (for improvements)

Phase 5: Validation Report

Generate comprehensive report at docs/validation/{feature-name}-validation.md:

# Validation Report: {feature-name}

**Date**: {timestamp}
**Branch**: feat/{feature-name}  
**Spec**: docs/specs/{feature-name}-spec.md
**Status**: ✅ PASS | ⚠️ PARTIAL | ❌ FAIL

## Summary
- Tests: {passed}/{total} passing
- Coverage: {percentage}% (target: 80%)
- Spec Alignment: {percentage}% complete

## Test Results
### Unit Tests
- Coverage: {percentage}%
- Passing: {count}
- Failing: {count}

### Integration Tests  
- Endpoints tested: {count}
- Database ops: ✅/❌
- External services: ✅/❌

### E2E Tests
- Critical paths: {passed}/{total}

## Spec Alignment
### Implemented ✅
- [List of correctly implemented features]

### Deviations ⚠️
- [List of partial/different implementations]

### Missing ❌
- [List of missing implementations]

## Recommendations
- [Specific fixes needed]
- [Optional improvements]

## Approval Status
- [ ] Ready for merge
- [ ] Requires fixes (see recommendations)

Phase 6: Resolution (if --fix flag)

Attempt automatic fixes for common issues:

• Add missing test files
• Fix test coverage gaps for simple functions
• Add missing error handling
• Update documentation
• Generate missing type definitions

Quality Gate Outcomes

Integration with Swarm Workflow

# Complete development workflow:
/skill:plan feature-name          # PRD → Spec → Tasks
/skill:swarm feature-name         # Plan and implement
/skill:validate feature-name      # Validate and approve

# If validation fails:
/skill:validate feature-name --fix     # Auto-fix common issues
# Manual fixes in feature branch
/skill:validate feature-name           # Re-validate

# When validation passes:
# Manual merge of feat/{feature-name} to dev

Example

User: /skill:validate user-avatar

Pi: Starting validation for user-avatar...

## Environment Setup
✅ Switched to feat/user-avatar  
✅ Dependencies up to date
✅ Test infrastructure ready

## Spec Alignment Analysis
📖 Loading spec: docs/specs/user-avatar-spec.md
🔍 Analyzing implemented code...

### API Endpoints
✅ POST /api/avatar/upload - matches spec
✅ GET /api/avatar/{userId} - matches spec  
⚠️  DELETE /api/avatar/{userId} - missing error handling for 404

### Data Models
✅ Avatar schema matches spec
✅ Database migrations present

### Security
✅ File type validation implemented
✅ Size limits enforced  
❌ Missing rate limiting (spec requirement)

## Test Execution

### Unit Tests
✅ 127/127 tests passing
✅ Coverage: 85% (target: 80%)

### Integration Tests  
✅ API endpoints: 12/12 passing
✅ Database operations: 5/5 passing
✅ File upload flow: 3/3 passing

### E2E Tests
✅ Avatar upload flow: 2/2 passing
⚠️  Avatar deletion flow: 1/1 passing (but missing rate limit test)

## Validation Summary
- **Status**: ⚠️ PARTIAL
- **Tests**: 143/143 passing (100%)
- **Coverage**: 85%
- **Spec Alignment**: 90%

## Issues Found
❌ Missing rate limiting implementation
⚠️  Incomplete error handling in delete endpoint

## Recommendations
1. Add rate limiting middleware to avatar endpoints
2. Improve error handling for 404 cases
3. Add integration test for rate limiting

Validation report saved: docs/validation/user-avatar-validation.md

Would you like me to attempt automatic fixes with /skill:validate user-avatar --fix?

Manual Remediation

When validation fails, use standard development workflow:

1. Address issues in feature branch
2. Run tests locally: npm test
3. Re-run validation: /skill:validate feature-name
4. Repeat until validation passes

Configuration

Optional validation config at .validate.json:

{
  "coverage": {
    "unit": 80,
    "integration": 70,
    "e2e": 50
  },
  "testCommand": "npm test",
  "coverageCommand": "npm run test:coverage",
  "e2eCommand": "npm run test:e2e",
  "autoFix": ["coverage", "docs", "types"],
  "strictMode": false
}

Related

• /skill:swarm - Implementation planning and orchestration
• /skill:plan - Planning workflow (PRD → Spec → Tasks)
• /skill:feature - Single-branch feature implementation
• docs/validation/ - Validation reports storage