plan-validation

jayprimer 的头像作者 jayprimer

在实施开始之前验证计划文档。检查歧义解决、先决条件和测试方法。使用时间:- 开始实施票证之前 - 用户说“验证计划”、“检查计划”、“准备好实施了吗?”- 完成 2-plan.md 和 3-spec.md 后 - 在 TDD 周期开始之前

📖 中文导读:在实施开始之前验证计划文档。检查歧义解决、先决条件和测试方法。使用时间:- 开始实施票证之前 - 用户说“验证计划”、“检查计划”、“准备好实施了吗?”- 完成 2-plan.md 和 3-spec.md 后 - 在 TDD 周期开始之前 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

name: plan-validation description: | Validate planning documents before implementation begins. Checks ambiguity resolution, prerequisites, and testing methods.

Use when: - Before starting implementation of a ticket - User says "validate plan", "check plan", "ready to implement?" - After completing 2-plan.md and 3-spec.md - Before TDD cycle begins

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

Check Source What
TBD/TODO markers 2-plan.md, 3-spec.md No unresolved placeholders
Open Questions 3-spec.md All questions marked RESOLVED
Technical Decisions 2-plan.md Decisions table exists

2. Prerequisites

Check Source What
Required docs ticket/ 1-definition, 2-plan, 3-spec exist
Test Environment 3-spec.md Setup section with prerequisites
Environment Variables 3-spec.md Documented or marked "none"
Mock Data 3-spec.md Table or "none needed"
Dependencies 1-definition.md Listed or marked "none"
Files to Modify 2-plan.md Table of affected files
Roadmap entry 3-plan/roadmap.md Ticket listed

3. Testing Methods

Check Source What
Unit Tests 3-spec.md Table with Input/Expected
Integration Tests 3-spec.md Setup/Action/Verify pattern
E2E Procedure 3-spec.md Setup + Execution + Verification
Verification checks 3-spec.md Specific checklist (table/list)
Manual inspection 3-spec.md Clear capture/save instructions
Edge Cases 3-spec.md Table format

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

Code Status Meaning
0 valid Plan ready for implementation
1 issues Has warnings/errors but can proceed
2 blocked Missing critical sections
3 not_found Ticket not found

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
```bash
export TEST_DB_URL=sqlite:///test.db
export LOG_LEVEL=DEBUG

Database Setup

pmc db migrate --test

### Testing Method Checks

E2E Test Procedure must have clear verification:

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