---
name: deep-plan
description: >
  Ultra-detailed planning mode for AI agents. Trigger this skill whenever a user wants to plan features, tasks, bug fixes, or changes to a codebase or project — BEFORE any code is written. Activates on phrases like "plan this", "create a plan", "deep plan", "ultra plan", "planning mode", "I want to add feature X", "fix these bugs", "what needs to change to...", or any request that involves understanding a project and mapping out what files/components need to be modified. Also triggers when the user uploads or references a project/codebase and describes features or problems they want addressed. DO NOT skip this skill for any non-trivial development planning task — it is the gold standard for thorough pre-implementation analysis.
---
 
# Deep / Ultra Plan Mode
 
A rigorous planning skill for AI agents. The goal: produce a complete, reviewer-ready plan that a developer (or AI agent) can execute confidently, without needing to ask follow-up questions mid-implementation.
 
> ⚠️ **DO NOT start code implementation.** This skill ends with a saved plan file. Tell the user to review the plan before any coding begins.
 
---
 
## Step 0 — Identify the Planning Mode
 
Determine which mode applies based on the user's request:
 
| Mode | When to use |
|------|-------------|
| **Feature / Task Mode** | User wants to add, change, or build something new |
| **Bug / Problem Mode** | User reports one or more problems to fix |
| **Mixed Mode** | Both features and bugs are present |
 
Announce the mode you're entering at the start of your response.
 
---
 
## Step 1 — Deep Requirements Gathering
 
### 1a. Parse the request
Extract every feature, task, or problem the user has described. List them explicitly. If any item is vague or ambiguous, flag it immediately.
 
### 1b. Ask clarifying questions (if needed)
Before proceeding, if critical information is missing, ask the user. **Always use structured choices** — never open-ended "tell me everything":
 
- Present multiple-choice options (2–5 choices) wherever possible
- Use yes/no for binary questions
- Use free-text input only when a choice list is impossible
- Ask no more than 5 questions at once; prioritize the most blocking unknowns
**Example question format:**
```
Before I build the plan, I need a few quick answers:
 
1. Where should the new dashboard route live?
   a) Inside the existing /app/routes directory
   b) As a new top-level /dashboard directory
   c) I'm not sure — you decide based on the project structure
 
2. Should this feature support mobile/responsive layout?
   a) Yes, full responsive
   b) Desktop-only for now
```
 
Wait for the user's answers before proceeding.
 
---
 
## Step 2 — Project Archaeology (Codebase Review)
 
Thoroughly explore the project before planning anything. Use all available tools (bash, file viewer, etc.) to understand the codebase.
 
### 2a. Map the project structure
- List all top-level directories and their purpose
- Identify the framework, language, build system, and package manager
- Note key config files (tsconfig, vite.config, package.json, .env.example, etc.)
### 2b. Trace relevant code paths
For **Feature Mode**: find all files touched by similar existing features. Trace data flow from UI → logic → API → DB.
 
For **Bug Mode**: locate the files where the reported symptoms appear. Trace backwards to find the root cause.
 
### 2c. Identify shared/reusable components
- Utility files, hooks, helpers, stores, context providers
- Shared types and interfaces
- Any abstraction layers (repositories, services, middleware)
### 2d. Generate architecture diagrams (when helpful)
When the project has non-obvious file relationships, produce:
- A file dependency diagram (Mermaid `graph` or `flowchart`)
- A data-flow diagram for the affected feature area
- A component tree (for frontend projects)
Use Mermaid syntax inside fenced code blocks labeled `mermaid`.
 
---
 
## Step 3 — Root Cause Analysis (Bug Mode only)
 
For each reported problem:
1. **Symptom** — What the user observes
2. **Affected file(s)** — Where the issue manifests
3. **Root cause** — The actual underlying bug (not just the symptom)
4. **Evidence** — Lines of code, logic errors, missing checks, etc.
5. **Fix strategy** — High-level approach to the fix
Present this as a structured table or numbered list before writing the plan.
 
---
 
## Step 4 — Write the Ultra Plan
 
Create a comprehensive, step-by-step implementation plan. Structure it as follows:
 
### Plan structure
 
```
# Ultra Plan: [Feature/Bug Title]
 
## Summary
One-paragraph description of what this plan accomplishes.
 
## Scope
- In scope: ...
- Out of scope: ...
 
## Architecture Notes
(Diagrams and structural observations here)
 
## Implementation Steps
 
### Step 1: [Title]
**Why**: Reason this step exists  
**Files affected**:
- `path/to/file.ts` — What changes and why
- `path/to/other.ts` — What changes and why
 
**Detailed changes**:
- In `ComponentX`: Add prop `onSubmit: (data: FormData) => void`
- In `useFormHook`: Expose new `isSubmitting` state
- In `api/routes.ts`: Add POST `/api/form` handler
 
### Step 2: [Title]
...
 
## Files Changed — Master Checklist
| File | Change Type | Reason |
|------|-------------|--------|
| src/components/Form.tsx | Modify | Add submit handler |
| src/api/routes.ts | Modify | New endpoint |
| src/types/index.ts | Modify | New FormData type |
| src/hooks/useForm.ts | Modify | Expose isSubmitting |
 
## Cross-Cutting Concerns
- Tests: Which test files need to be added or updated
- Types: Any TypeScript changes that ripple across files
- Env vars: New environment variables required
- Migrations: DB schema changes needed
- Documentation: README or API docs to update
 
## Risk & Edge Cases
- List any gotchas, potential regressions, or tricky edge cases
- Flag anything that needs a second opinion
 
## Review Checklist
- [ ] Every affected file is listed
- [ ] No file was missed that imports/uses changed code
- [ ] Types are consistent across all modified interfaces
- [ ] Tests are accounted for
- [ ] No implementation has started
```
 
---
 
## Step 5 — Full-Project Re-Scan (Impact Check)
 
After drafting the plan, perform a second pass over the entire project:
 
1. For every file in the plan, check: **what else imports or depends on this file?**
2. For every type or interface changed, check: **where else is this type used?**
3. For every API route added/modified, check: **what clients consume this endpoint?**
Add any missed files to the plan. Annotate them with `(discovered in impact check)`.
 
---
 
## Step 6 — Self-Review
 
Before saving, review the plan against this checklist:
 
- [ ] All originally requested features/bugs are covered
- [ ] Every step has a clear "why"
- [ ] Every changed file is listed with specific changes
- [ ] No vague steps like "update the component" — always specify what to update
- [ ] Edge cases and risks are called out
- [ ] The plan is executable without further clarification (or outstanding questions are noted)
- [ ] No code has been written
If any item fails, expand that section before saving.
 
---
 
## Step 7 — Save the Plan
 
Save the completed plan as a Markdown file:
 
- **Filename**: `PLAN_[feature-or-bug-slug]_[YYYY-MM-DD].md`
- **Location**: Project root, or ask the user where to save it
- Present the file to the user using `present_files`
End your response with:
 
> ✅ **Plan saved.** Please review it carefully before any implementation begins. If anything needs adjustment, let me know and I'll revise the plan.
 
---
 
## Behavior Rules
 
- **Do not start writing the implementation code** during this skill.
- **Always ask before assuming** on ambiguous requirements — but batch questions and use choices.
- **Always do the impact check** (Step 5) — it catches the most common planning failures.
- **Be specific about file paths** — "the auth module" is not a file path.
- **Use diagrams freely** — a Mermaid diagram often saves 10 paragraphs of explanation.
- If the user says "just start" or "skip the plan", gently remind them that this skill produces a plan for their review, and confirm they want to skip it.