validate-plan

name	validate-plan
description	Validates implemented code against technical specifications, runs comprehensive tests, and ensures alignment before merge. Third prong of the development workflow after planning and orchestration.

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

Status	Criteria	Action
✅ PASS	All tests pass, 80%+ coverage, full spec alignment	Approve for merge
⚠️ PARTIAL	Tests pass, good coverage, minor spec gaps	Review recommendations, may proceed
❌ FAIL	Test failures, low coverage, or major spec gaps	Block merge, remediation required

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