Plan Validation

Validate planning documents are complete and actionable before implementation.

Prerequisites

ALWAYS run /pmc:kb first to understand KB structure.

Quick Start

# Validate ticket plan
python scripts/validate_plan.py T00021

# Human-readable output
python scripts/validate_plan.py T00021 --format text

What Gets Validated

1. Ambiguity Resolution

2. Prerequisites

3. Testing Methods

Output

{
  "ticket_id": "T00021",
  "status": "issues",
  "summary": {
    "errors": 2,
    "warnings": 3,
    "passed": 12,
    "failed": 2
  },
  "checks_passed": ["3-spec.md exists", "E2E has Setup subsection", ...],
  "checks_failed": ["Missing E2E Verification subsection", ...],
  "issues": [
    {
      "severity": "error",
      "category": "testing",
      "message": "E2E Test Procedure missing 'Verification' subsection",
      "file": "3-spec.md",
      "line": 0
    }
  ]
}

Exit Codes

Validation Categories

Ambiguity Checks

Detects unresolved planning items:

# BAD - Will flag as error
## Steps
1. Configure the thing TBD
2. TODO: figure out auth

# GOOD - Resolved
## Steps
1. Configure OAuth2 with client_credentials flow
2. Auth handled by existing middleware (see 5-code-maps/auth.md)

Open Questions section must have all items resolved:

# BAD
## Open Questions
1. Which database driver to use?
2. How to handle rate limiting?

# GOOD
## Open Questions
1. Which database driver to use? - RESOLVED: asyncpg for performance
2. How to handle rate limiting? - RESOLVED: Use existing RateLimiter class

Prerequisites Checks

Test Environment Setup must be actionable:

# BAD - Vague
## Test Environment Setup
Set up the test environment.

# GOOD - Specific
## Test Environment Setup

### Prerequisites
- Python 3.11+
- Docker running
- `pmc` installed from source

### Environment Variables

export TESTDBURL=sqlite:///test.db export LOG_LEVEL=DEBUG

### Database Setup

pmc db migrate --test

Testing Method Checks

E2E Test Procedure must have clear verification:

# BAD - No verification specifics
## E2E Test Procedure
Run the workflow and check it works.

# GOOD - Specific verification
## E2E Test Procedure

### Setup
1. Create test directory: `mkdir /tmp/test-T00021`
2. Initialize: `cd /tmp/test-T00021 && pmc init`

### Execution
1. Run: `pmc run workflow.json -i ticket_id=T99990`
2. Wait for completion

### Verification

| Check | Expected |
|-------|----------|
| Exit code | 0 |
| Output contains | "Workflow completed successfully" |
| File created | `.pmc/docs/tickets/T99990/5-final.md` |
| Screenshot | Save terminal output to `evidence/T00021-e2e.png` |

### Teardown
1. `rm -rf /tmp/test-T00021`

Manual Inspection

When manual verification needed, document how to capture evidence:

### Verification

| Check | Expected | How to Verify |
|-------|----------|---------------|
| UI renders | Dashboard shows | Screenshot: `evidence/dashboard.png` |
| Animation smooth | No jank | Record: 5-second screen capture |
| Colors correct | Brand colors | Visual compare with `assets/brand.png` |

Integration with Dev Workflow

Run before starting implementation:

PLAN
  ├── Create 1-definition.md
  ├── Create 2-plan.md
  ├── Create 3-spec.md
  │
  ▶ VERIFY: validate_plan.py T0000N
  │         └── Exit 0? → Ready for IMPLEMENT
  │         └── Exit 1? → Review warnings, fix if needed
  │         └── Exit 2? → BLOCKED - fix missing sections
  │
  └── IMPLEMENT begins

Checklist

Before running validation:

• 1-definition.md has Summary, Scope, Success Criteria
• 2-plan.md has Approach, Steps, Technical Decisions, Files to Modify
• 3-spec.md has Test Environment, Test Cases, E2E Procedure, Edge Cases
• All TBD/TODO resolved
• Open Questions answered
• E2E has Setup/Execution/Verification
• Manual steps have capture instructions