# Validating Plans

> Systematically validate implementation plans before execution - catches hallucinations, TDD violations, missing references, and temporal drift that derail implementations. Use after writing-plans skill creates a plan document. Use when this capability is needed.

- Skill: `tomevault-io/validating-plans` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/validating-plans`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/validating-plans/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/validating-plans

---


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

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

```markdown
> **📁 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

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

```json
{
  "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

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

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

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

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/jmagar) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-16 -->