Validating Plans

Version History

• v1.0.0 (2025-12-08): Initial release with agent-based validation
  • Three specialized validators: static-analyzer, environment-verifier, architecture-reviewer
  • Parallel execution for efficiency
  • TodoWrite integration for plan fixes
  • GitHub issue creation post-validation

Overview

Systematically audit implementation plans before execution. Catch hallucinations, TDD violations, missing pieces, and logical gaps that derail implementations. Trust nothing - verify everything that can be verified.

Announce at start: "I'm using the validating-plans skill to audit this implementation plan."

Input: A plan document (from writing-plans skill) Output: Validation report with issues categorized by severity

Workflow Position: Runs between writing-plans and executing-plans:

1. Brainstorm → 2. Write-plan → 3. Validate-plan → 4. Execute-plan → 5. Finish-branch

---

When to Use This Skill

Use this skill when:

• A plan document has been created by the writing-plans skill
• User explicitly requests validation with /validate-plan
• About to execute a plan and want to verify assumptions first
• Returning to an older plan that may have drifted

Do NOT use this skill for:

• Validating code (use code-review skills instead)
• Planning implementation (use writing-plans instead)
• Executing plans (use executing-plans instead)

---

Validation Process

Step 1: Locate and Load Plan

Accept plan file path as argument:

PLAN_FILE="$1"

# Validate plan file exists
if [[ -z "$PLAN_FILE" ]]; then
    echo "🔴 ERROR: Plan file path required"
    echo "Usage: /validate-plan <path-to-plan-file>"
    exit 1
fi

if [[ ! -f "$PLAN_FILE" ]]; then
    echo "🔴 ERROR: Plan file not found: $PLAN_FILE"
    exit 1
fi

echo "📋 Validating: $PLAN_FILE"

Step 2: Add Organization Note to Plan

CRITICAL: Before running validation agents, add organization note to the plan file.

Add this note to the top of the plan file (after the title/header):

> **📁 Organization Note:** When this plan is fully implemented and verified, move this file to `docs/plans/complete/` to keep the plans folder organized.

This is the ONLY edit made to the plan during validation phase.

Step 3: Launch Parallel Validation Agents

Spawn 3 parallel validation agents using the Task tool in a SINGLE message with 3 Task tool calls:

Agent 1: TDD Compliance Auditor

• Reference: references/validating-plans-tdd-compliance.md
• Validates: Red-green-refactor cycles, test quality, anti-patterns
• Returns: TDD compliance report with violations

Agent 2: Reality Check Verifier

• Reference: references/validating-plans-reality-check.md
• Validates: Files exist, packages real, APIs valid, no fake imports
• Returns: Anti-hallucination verification report

Agent 3: Drift Detector

• Reference: references/validating-plans-drift-detection.md
• Validates: Files changed after plan, uncommitted changes, dependency updates
• Returns: Temporal drift analysis

Launch Pattern:

Task 1: TDD Compliance
- subagent_type: "general-purpose"
- prompt: "Execute the validating-plans:tdd-compliance skill in references/validating-plans-tdd-compliance.md to audit TDD compliance in: $PLAN_FILE"

Task 2: Reality Check
- subagent_type: "general-purpose"
- prompt: "Execute the validating-plans:reality-check skill in references/validating-plans-reality-check.md to verify all references in: $PLAN_FILE"

Task 3: Drift Detection
- subagent_type: "general-purpose"
- prompt: "Execute the validating-plans:drift-detection skill in references/validating-plans-drift-detection.md to detect temporal drift in: $PLAN_FILE"

CRITICAL: All 3 agents MUST be launched in ONE message with 3 tool calls.

Step 4: Aggregate Results

After all 3 agents complete, aggregate their findings into a unified validation report.

Severity Levels

🔴 BLOCKER   - Execution will fail. Plan references non-existent things. Must fix.
🟠 CRITICAL  - High risk of rework. TDD violation, stale line numbers. Should fix.
🟡 WARNING   - Suboptimal. Missing edge cases, vague steps. Consider fixing.
🔵 NIT       - Style/preference. Fix if time permits.

Validation Report Template

# Plan Validation Report: [Feature Name]

**Plan:** `<plan-file-path>`
**Validated:** [timestamp]
**Verdict:** ✅ PASS | ⚠️ PASS WITH NOTES | 🔴 NEEDS REVISION

---

## Verification Summary

| Check | Status | Notes |
|-------|--------|-------|
| TDD Compliance | ✅/🔴 | [from agent 1] |
| File Targets | ✅/🔴 | [from agent 2] |
| Packages/Deps | ✅/🔴 | [from agent 2] |
| API Signatures | ✅/🔴 | [from agent 2] |
| Drift Detection | ✅/🟠/🔴 | [from agent 3] |

---

## Issues Found

### 🔴 BLOCKERS (N)
[Aggregated from all agents]

### 🟠 CRITICAL (N)
[Aggregated from all agents]

### 🟡 WARNINGS (N)
[Aggregated from all agents]

---

## Drift Analysis
[From agent 3: drift-detection]

**Plan created:** [timestamp]
**Drift Risk:** 🔴 HIGH | 🟠 MEDIUM | 🟡 LOW | ✅ NONE

---

## Sign-off Checklist

- [ ] All blockers resolved
- [ ] Critical issues addressed or explicitly risk-accepted
- [ ] TDD order verified for all tasks
- [ ] All external references verified to exist
- [ ] File drift acknowledged and assumptions updated

**Validated by:** Claude Code
**Ready for execution:** YES / NO

Step 5: Create TodoWrite Tasks for Plan Fixes

CRITICAL: TodoWrite creates todos to FIX THE PLAN, not to fix the problems the plan would create.

IF validation finds blockers or critical issues:

Create one todo PER blocker/critical issue:

{
  "content": "Fix plan blocker: [specific issue in plan]",
  "activeForm": "Fixing plan blocker: [specific issue]",
  "status": "pending"
}

Examples of CORRECT todos:

✅ "Fix plan blocker: Update Task 3 to import from starlette.responses instead of hallucinated fastapi_utils" ✅ "Fix plan critical: Reorder Task 2 steps to test-first (TDD violation)" ✅ "Fix plan blocker: Change Task 5 target from non-existent src/services/legacy_auth.py to correct path"

Examples of WRONG todos (these fix CODE, not PLAN):

❌ "Fix: Install fastapi_utils package" (no, fix the plan to not use it) ❌ "Fix: Create missing src/services/legacy_auth.py file" (no, fix the plan path) ❌ "Add error handling to Task 3" (this changes implementation, not plan)

Step 6: Provide Handoff Message

If ✅ PASS (no issues):

"Plan validated - all references verified, TDD compliance confirmed. No plan fixes needed.

Ready to proceed with GitHub issue creation or direct execution."

If 🔴 NEEDS REVISION (blockers/criticals found):

"Found N blockers and M critical issues in the plan.

Created N+M TodoWrite tasks to fix the PLAN document:

1. Fix plan blocker: [summary]
2. Fix plan critical: [summary]

Complete these todos to update the plan file, then re-run /validate-plan to verify fixes."

If ⚠️ PASS WITH NOTES (warnings only):

"Plan validation passed with N warnings (non-blocking).

Warnings noted but no todos created (not critical for execution).

Ready to proceed with GitHub issue creation or direct execution."

---

GitHub Issue Creation (Post-Validation)

After successful validation (✅ PASS or ⚠️ PASS WITH NOTES), offer to create GitHub issue.

Prerequisites Check

# Verify GitHub CLI installed
if ! command -v gh &>/dev/null; then
    echo "🔴 GitHub CLI not installed"
    echo "Install: https://cli.github.com/"
    exit 1
fi

# Verify gh authenticated
if ! gh auth status &>/dev/null; then
    echo "🔴 GitHub CLI not authenticated"
    echo "Run: gh auth login"
    exit 1
fi

# Detect repository from git remote
REPO_URL=$(git remote get-url origin 2>/dev/null)
if [[ -z "$REPO_URL" ]]; then
    echo "🔴 No git remote 'origin' found"
    exit 1
fi

# Extract owner/repo from URL
REPO=$(echo "$REPO_URL" | sed -E 's|.+github\.com[:/]([^/]+/[^/]+)(\.git)?$|\1|')
echo "📦 Repository: $REPO"

User Confirmation Prompt

After validation passes:

✅ Validation Complete

**Plan:** `<plan-file-path>`
**Status:** PASS (ready for execution)

**Next Step: Create GitHub Issue**

Would you like to create a GitHub issue containing this validated plan?

The issue will include:
- Full plan content as issue body
- Label: "implementation-plan"
- Label: "validated"

Repository: <repo>

Create issue? (y/n):

Issue Creation Logic

If user confirms (y):

#!/bin/bash
PLAN_FILE="$1"
REPO="$2"

# Extract plan title from header
PLAN_TITLE=$(grep -m1 '^# ' "$PLAN_FILE" | sed 's/^# //' | sed 's/ Implementation Plan$//')

# Read full plan content
PLAN_BODY=$(cat "$PLAN_FILE")

# Add validation metadata to issue body
ISSUE_BODY="**Validated Plan** ✅

Validation completed: $(date -u +"%Y-%m-%d %H:%M:%S UTC")

---

$PLAN_BODY

---

**Validation Notes:**
- All file references verified
- Dependencies confirmed to exist
- TDD compliance checked
- Ready for implementation

**Implementation:**
Use \`/superpowers:executing-plans\` in Claude Code to execute this plan task-by-task.
"

# Create issue using gh CLI
echo "Creating GitHub issue..."

ISSUE_URL=$(gh issue create \
  --repo "$REPO" \
  --title "Implementation: $PLAN_TITLE" \
  --body "$ISSUE_BODY" \
  --label "implementation-plan" \
  --label "validated" \
  2>&1)

if [[ $? -eq 0 ]]; then
    echo "✅ GitHub issue created successfully!"
    echo "🔗 $ISSUE_URL"
else
    echo "🔴 Failed to create issue:"
    echo "$ISSUE_URL"
    exit 1
fi

---

Validation Checks Summary

Phase 1: TDD Compliance (Agent 1)

• Red-green-refactor cycle order
• Test quality and naming
• Expected error messages
• Anti-patterns (batching, implementation-first)

Phase 2: Reality Verification (Agent 2)

• File existence and line numbers
• Package existence in registries
• API signatures and exports
• Internal import dependencies
• Command availability

Phase 3: Drift Detection (Agent 3)

• File modifications after plan creation
• Uncommitted working tree changes
• Dependency file updates
• Overall drift risk assessment

---

Integration with Superpowers Workflow

Plan Header Verification:

Verify the plan contains the required header from writing-plans:

> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

Plan Location Standard:

Validate plan is in correct location: docs/plans/YYYY-MM-DD-<feature-name>.md

Batch Execution Compatibility:

• Verify tasks can be batched independently (default 3 tasks)
• Flag tasks with hidden dependencies
• Warn if batch size would be problematic

TDD 5-Step Pattern:

Validate each task follows this exact sequence:

1. Write failing test
2. Run to verify fail
3. Write minimal code
4. Run to verify pass
5. Commit

---

Common Validation Scenarios

Scenario 1: Plan Validates Clean

$ /validate-plan docs/plans/feature.md
📋 Validating: docs/plans/feature.md
✅ All checks passed
✅ No drift detected

Create GitHub issue? (y/n): y
✅ Issue created: #123

Ready for execution via /superpowers:executing-plans

Scenario 2: Plan Has Blockers

$ /validate-plan docs/plans/feature.md
🔴 2 blockers found
🟠 1 critical issue found

Created 3 TodoWrite tasks to fix plan:
1. Fix plan blocker: Hallucinated package
2. Fix plan blocker: File not found
3. Fix plan critical: TDD violation

Complete todos → re-run /validate-plan

Scenario 3: Drift Detected

$ /validate-plan docs/plans/feature.md
⚠️ PASS WITH NOTES

🟠 Drift detected:
  - src/api/routes.py modified 2 days after plan
  - Recommendation: Review plan assumptions

Create GitHub issue? (y/n): y
✅ Issue created with drift warnings: #124

---

Remember

• Launch all 3 validation agents in parallel (single message, 3 tool calls)
• Only add organization note to plan (no other edits during validation)
• TodoWrite tasks fix THE PLAN, not the code
• Distinguish validation verdicts: ✅ PASS, ⚠️ PASS WITH NOTES, 🔴 NEEDS REVISION
• Offer GitHub issue creation only after successful validation
• Validation sits between writing-plans and executing-plans in workflow