deep-plan

name	deep-plan
description	Research-validated planning — research → plan → verify cycle for high-confidence implementation plans
scope	core
context	fork
version	1.0.0
user-invocable	true
argument-hint	<topic-or-issue>
teams-compatible	true

Deep Plan Skill

Research-validated planning that eliminates the gap between research assumptions and actual code. Orchestrates a 3-phase cycle: Discovery Research → Reality-Check Planning → Plan Verification.

Teams-compatible — works both from the main conversation (R010) and inside Agent Teams members. When used in Teams, the member directly executes the 3-phase workflow without Skill tool invocation.

Full phase detail: guides/deep-plan/phases.md

Usage

/deep-plan <topic-or-issue>
/deep-plan "implement caching layer for API responses"
/deep-plan #325 new authentication system
/deep-plan Rust async runtime migration

Problem Solved

Research-only analysis produces findings based on assumptions about the codebase. These assumptions often diverge from reality:

Assumption	Reality	Impact
"Feature X is missing"	Already implemented	Wasted effort on duplicate work
"Pattern Y is needed"	Partially exists	Over-engineering existing code
"Library Z is required"	Already a dependency	Unnecessary integration effort

/deep-plan solves this by cross-referencing research findings against actual code before committing to a plan.

Workflow Contract

3-phase pipeline:

Phase	Name	Key Activity	Model
1	Discovery Research	10-team parallel via /research	sonnet + opus
2	Reality-Check Planning	3 Explore agents + gap analysis	haiku + opus
3	Plan Verification	3 focused verification teams	sonnet + opus

Execution Rules

Rule	Detail
Phase 1	Full /research skill invocation (10 teams)
Phase 2	Max 3 parallel Explore agents (R009)
Phase 3	Max 3 parallel verification teams (R009)
Orchestrator only	Main conversation manages all phases (R010)
Intent display	Show phase plan before execution (R015)
Ecomode	Auto-activate for team result aggregation (R013)
REVISE limit	Max 2 cycles before user escalation

Differentiation

Skill	Scope	Code Verification	Phases
/research	Analysis only	None — assumption-based	1
Plan mode	Planning only	Yes — code exploration	1
/structured-dev-cycle	Full implementation	Yes — stage-by-stage	6
/deep-plan	Analysis + Planning + Verification	3-pass cross-verification	3

Artifact Output (R006/R010)

Phase 3 verification report path: .claude/outputs/sessions/{YYYY-MM-DD}/deep-plan-{HHmmss}.md

Under mode: "bypassPermissions", subagents write directly to .claude/outputs/ with Write/Edit — no temp-script wrapping is needed (CC v2.1.121+, #1101). When spawning the final synthesis agent to write this artifact, include verbatim in the agent prompt:

**Artifact output (for this task)**

Write the verification report to `.claude/outputs/sessions/<date>/deep-plan-<HHmmss>.md`
using the Write tool directly (create the directory if needed). Your Agent tool call
runs under `mode: "bypassPermissions"`, so direct Write/Edit on `.claude/` is permitted.

See R006 "Sensitive Path Handling" (CC v2.1.121+ direct-write convention).

Agent Teams (R018)

Phase	Without Agent Teams	With Agent Teams
Phase 1	Delegates to /research (handles internally)	Delegates to /research (handles internally)
Phase 2	Up to 3 Explore agents via Agent tool	Up to 3 Explore agents via Agent tool (below threshold)
Phase 3	3 agents via Agent tool	3 agents — prefer Agent Teams for coordination

Post-Completion Advisory

After PASS verdict:

[Advisory] Verified plan ready for implementation.
├── For complex implementations (10+ files): /structured-dev-cycle
├── For parallel task execution: superpowers:subagent-driven-development
└── For simple tasks (< 3 files): proceed directly

Permission Mode

When spawning agents via the Agent tool during this skill's execution, always pass mode: "bypassPermissions". The Agent tool default (acceptEdits) overrides agent frontmatter permissionMode, causing permission prompts during unattended execution.