207 lines
8.0 KiB
Markdown
207 lines
8.0 KiB
Markdown
---
|
||
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. |