| name | plan-validator |
| description | Validate implementation plans for completeness, specificity, and actionability. Catches vague language, missing sections, and untestable outcomes. |
| user-invocable | true |
| argument-hint | [path-to-plan.md] |
| allowed-tools | Bash(python:*), Bash(git status), Read, Glob |
| tags | ["meta"] |
Plan Validator
Validates PLAN.md files for structural completeness, specificity, and actionability before the approval gate.
When to Use
- After drafting a PLAN.md during the Plan phase
- Before presenting a plan for user approval
- To review an existing plan's quality
Usage
/plan-validator # Validates PLAN.md in current session dir
/plan-validator path/to/PLAN.md # Validates a specific file
Process
Step 1: Locate the Plan
If no path argument is provided:
- Check the current session directory for
PLAN.md
- If not found, ask the user for the path
Step 2: Run Validation
Run from the skill directory (skills/plan-validator/):
python scripts/validate_plan.py <path> --verbose
Step 3: Report Results
Present the validation output to the user:
- Score (0-100) and verdict (PASS >= 70, NEEDS WORK < 70)
- Errors (blocking issues)
- Warnings (quality concerns)
Step 4: Fix and Re-validate
If the plan scores NEEDS WORK:
- Address each error finding
- Re-run validation to confirm the fix
- Present the updated score
Checks Performed
| # | Check | What It Validates |
|---|
| 1 | Target repos | At least one repo or directory listed |
| 2 | Files to modify | Explicit file paths, not vague areas |
| 3 | Ordered steps | Numbered or sequenced implementation steps |
| 4 | Steps reference files | Each step mentions at least one file path |
| 5 | Risks section | Non-empty risks or assumptions section |
| 6 | Verification section | How to confirm correctness is described |
| 7 | Vague language | Flags: "should work", "might need", "probably", "as needed", "etc." |
| 8 | Oversized code blocks | Code blocks >15 lines (plans describe, not implement) |
| 9 | Scope boundary | Explicit exclusions or out-of-scope stated |
| 10 | Traceability table | Discovery findings mapped to plan steps |
| 11 | Testable outcomes | At least one step references tests, builds, or verification |
| 12 | Step file specificity | Each step names a specific file path, not a vague area (e.g., "update cli/fotw/services/catalog.py" not "update the config") |
| 13 | Per-step verification | Each step has an explicit verification action (run test, lint, build, or manual check) |
| 14 | Structure section | Plan includes a phase breakdown or dependency ordering (not just a flat list of steps) |
| 15 | Git branch | A branch name is specified (e.g., feature/, fix/, refactor/) |
| 16 | Git commit plan | Commit checkpoints with messages and a PR title/description are included |
Resources
scripts/
| Script | Purpose |
|---|
validate_plan.py <file> [--verbose] [--json] | Run all validation checks on a PLAN.md |
