check-your-plan

name	check-your-plan
description	Validates AI implementation plans before execution. Use when user says "check your plan", "validate this plan", "review the plan", or "is this plan good". Launches 5 parallel validators + devil's advocate.
allowed-tools	Task, Read, Glob, Grep, AskUserQuestion
version	1.1.0

Check Your Plan

Validate AI-generated implementation plans before execution to catch hallucinations, pattern violations, and scope creep.

<when_to_use>

When to Use

Invoke when user says:

• "check your plan"
• "validate this plan"
• "review the plan"
• "is this plan good"
• After Claude presents an implementation plan
• Before starting significant implementation work

Different from check-your-code/work: check-your-code and check-your-work review written code. check-your-plan reviews the PLAN before code is written. </when_to_use>

Workflow Overview

Phase	Agents	Action
1	-	Plan Discovery (locate plan, extract content)
2	5 parallel	Plan Validation (specialized reviewers)
3	1	Devil's Advocate (challenge all findings)
4	-	Report + User Decision

For Phase 2 details: references/phase-2-plan-validators.md For Phase 3 details: references/phase-3-devil-advocate.md For report format: templates/plan-assessment.md

Agent Summary

Phase 2 (5 Parallel)

Agent	Focus
completeness-checker	All requirements addressed? 70% problem? Vague steps?
pattern-compliance-checker	CLAUDE.md rules? TanStack Query? Zod? File conventions?
feasibility-checker	Hallucinated APIs? Real file paths? Valid dependencies?
risk-assessor	Security gaps? Missing error handling? Rollback plan?
scope-discipline-checker	Over-engineering? Scope creep? Simplest solution?

Phase 3 (Devil's Advocate)

Agent	Focus
devil-advocate	Challenge all findings, reduce false positives

Severity Classification

Level	Meaning	Example
P0	Plan will fail	Hallucinated API, wrong file path, missing dep
P1	Major pattern violation	useState+service, handwritten interface, no org_id
P2	Could be better	Minor pattern deviation, missing edge case
P3	Suggestion	Over-engineering detected, style preference

P0 requires evidence: "File X doesn't exist" not just "might be wrong"

<approval_gates>

Approval Gates

Gate	Phase	Question
Scope	1	"Review this plan?" (if plan >50 lines)
Action	4	"Revise plan / Proceed as-is / Start over?"

</approval_gates>

Phase 1: Plan Discovery

1. Locate the plan to validate:

   • Check for plan file path in conversation context
   • Look in .claude/plans/ for recent plan files
   • If no plan file, check if plan was stated inline in conversation

2. Extract plan content and metadata:

   • Files to be modified
   • Steps/tasks count
   • Dependencies mentioned

3. If plan >50 lines, use AskUserQuestion to confirm scope

Phase 2: Plan Validation (5 Parallel)

Launch ALL 5 agents in a single message with multiple Task calls. See references/phase-2-plan-validators.md for agent prompts.

Provide each agent:

• Full plan content
• Original user request (from conversation context)
• Relevant pattern file content (load from claude-patterns/)

Phase 3: Devil's Advocate

Launch 1 agent to challenge ALL findings from Phase 2. See references/phase-3-devil-advocate.md for agent prompt.

Provide:

• All findings from Phase 2
• Plan content for context verification

Output: Validated findings with status (CONFIRMED/DOWNGRADED/DISMISSED/UPGRADED)

Phase 4: Report + User Decision

1. Generate report using templates/plan-assessment.md
2. Present findings grouped by severity (P0, P1, P2, P3)
3. Use AskUserQuestion:

{
  questions: [
    {
      question: "How would you like to proceed with this plan?",
      header: "Action",
      options: [
        {
          label: "Revise plan",
          description:
            "Update plan to address P0/P1 findings before implementing",
        },
        {
          label: "Proceed as-is",
          description: "Accept the plan and start implementation",
        },
        {
          label: "Start over",
          description: "Request a completely new plan approach",
        },
      ],
      multiSelect: false,
    },
  ];
}

<key_checks>

Key Validation Checks

Completeness (The "70% Problem")

• Are hard parts (error handling, edge cases, testing) as detailed as easy parts?
• Does plan address ALL original requirements?
• Are there vague steps like "implement the business logic"?

Pattern Compliance

• TanStack Query for data fetching (not useState + service calls)
• Zod schemas in src/types/forms/ (not handwritten interfaces)
• mutateAsync in modal forms (not mutate())
• contactFilters.ts for contact filtering (not inline filters)
• notifyApi for notifications (not direct useToast)
• organization_id filter on all queries

Feasibility (Hallucination Detection)

• Do referenced files actually exist?
• Do referenced functions have correct signatures?
• Are dependencies at correct versions?
• Are API endpoints real?

Risk Assessment

• Missing security considerations?
• No error handling for failure scenarios?
• No rollback plan for data mutations?
• No testing strategy?

Scope Discipline

• Does plan stay focused on original request?
• Signs of over-engineering (abstractions for one-time ops)?
• Signs of scope creep (unrelated "improvements")?

</key_checks>

What This Skill Does NOT Check

• Runtime behavior (requires execution)
• Actual code quality (use check-your-code after implementation)
• Bug detection (use check-your-work after implementation)
• Test coverage (use test runner)
• Build errors (use typecheck/lint)

For comprehensive quality: check-your-plan (before) + check-your-code + check-your-work (after)

<quick_reference>

Quick Reference

Pattern files checked for compliance:

• CLAUDE.md
• tanstack-query-patterns.md
• zod-form-patterns.md
• react-typescript-antipatterns.md
• modal-form-patterns.md
• notification-patterns.md
• settings-patterns.md

Common P0 findings:

• Hallucinated file path: src/services/foo.ts doesn't exist
• Hallucinated API: useAccounts() hook doesn't exist
• Missing dependency: Plan uses package not in package.json

Common P1 findings:

• useState + service call pattern (should use TanStack Query)
• Handwritten interface (should use Zod schema)
• Missing org_id filter (security violation) </quick_reference>

References

• references/phase-2-plan-validators.md - All 5 validator agents
• references/phase-3-devil-advocate.md - Challenge agent
• templates/plan-assessment.md - Report format

<version_history>

Version History

• v1.1.0 (2025-01-18): AI optimization updates

  • Add blockquote summary after title
  • Eliminate vague pronouns ("Those skills" → explicit skill names)

• v1.0.0 (2025-01-12): Initial release

  • 4-phase workflow with 5 parallel validators
  • Devil's advocate challenge phase
  • P0-P3 severity aligned with codebase patterns
  • Based on research: 3 Cs framework, 70% problem detection, hallucination checking

</version_history>