# Validate Plan

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

- Skill: `l3wi/validate-plan` (Agent Skill)
- Install (CLI): `npx skillmds@latest add l3wi/validate-plan`
- Raw SKILL.md: https://api.skillmd.com/api/skills/l3wi/validate-plan/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: l3wi (https://skillmd.com/u/l3wi)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/l3wi/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

```bash
/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**
   ```bash
   # 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`:

```markdown
# 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

```bash
# 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`:
```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