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 |

## Lightweight Mode (conditional)

Deep Plan MAY substitute a lightweight pass for the full 3-phase pipeline when the conditions defined in `auto-dev.yaml`'s `## Cross-tier — Lightweight Skill-Mode Substitution` section are met — this skill does not restate those conditions; read them from that section before invoking lightweight mode. The resulting plan artifact or output MUST state which mode ran (`mode: full` or `mode: lightweight`) and MUST include the justification log required by that section.

## Positive-Control Gate (Search/Retrieval Experiment Plans)

When a plan's Phase 1/2 measures a search or retrieval experiment (a new lane, ranking knob, or similar), do NOT trust a negative or neutral result until a positive control confirms the measurement can detect an effect — verify that the change moves candidates for at least one real query from the actual query distribution. If it does not, report the result as "measurement inconclusive", not "no effect".

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