Deep Plan

Deep Plan

Disciplined workflow that prevents wasted effort by separating thinking from typing. Never write code until the user has reviewed and approved a written plan.

Workflow

Research → Plan → [Interview] → Annotate (1-6x) → Todo List → Implement → Feedback → Archive

[Interview] is optional — an interactive Q&A to resolve ambiguities before annotation. See Phase 2 reference for triggers and process.

Critical guard: Do NOT advance to the next phase unless the user explicitly says to. When in doubt, ask.

Phases

Each phase has detailed instructions in its reference file. Read the relevant file when entering that phase.

Templates

Use these when creating artifacts:

• Research: assets/templates/research-template.md
• Plan: assets/templates/plan-template.md

Scripts

Reference Files

Hard Constraints

These are non-negotiable. Violating any of these is a workflow failure.

Key Principles

• The plan is shared mutable state. Both you and the user edit it. It persists across compaction.
• Single long sessions. Research through implementation in one conversation.
• Implementation should be boring. Creative decisions happen in annotation cycles.
• Never speculate about unread code. If the plan references a file, read it first.
• Scope discipline. If the user cuts something from the plan, it's cut. Don't sneak it back in.

Credit

This workflow is based on How I Use Claude Code by Boris Tane.

Plan: [Feature/Change Name]

Goal

[What this change achieves in 1-2 sentences]

Approach

[Detailed explanation of the implementation strategy]

Changes

[Section 1: e.g., Schema Changes]

Files: path/to/file.ts

[Explanation of what changes and why]

// Code snippet showing the actual change

[Section 2: e.g., API Layer]

Files: path/to/file.ts

[Explanation]

// Code snippet

Considerations

• [Trade-off or design decision with rationale]
• [Migration/backwards compatibility notes]
• [Performance implications if any]

Tasks

Phase 1: [Phase Name]

• [ ] [Atomic, verifiable task]
• [ ] [Atomic, verifiable task]

Phase 2: [Phase Name]

• [ ] [Atomic, verifiable task]
• [ ] [Atomic, verifiable task]

---

Ready for your review. Add any inline notes and I'll update the plan accordingly.

Research: [System/Module Name]

Overview

[What this system does in 2-3 sentences]

Architecture

Key Files

Key Abstractions

[List the main classes, functions, or modules and what each is responsible for]

Data Flow

[Trace how data moves through the system — entry point to storage/output]

Existing Patterns

[Patterns that new code must respect: caching, error handling, naming conventions, ORM usage, etc.]

Edge Cases & Invariants

[Implicit assumptions, ordering dependencies, things that break if violated]

Findings

[Anything notable: bugs found, potential issues, undocumented behavior, technical debt]

deep-plan

A structured workflow skill for AI-assisted development. Separates planning from execution to prevent wasted effort.

What It Does

Research the codebase, write a plan, let the user annotate the plan until it's right, then execute without stopping.

Research → Plan → [Interview] → Annotate (1-6x) → Todo List → Implement → Feedback → Archive

The core principle: never let the agent write code until you've reviewed and approved a written plan.

Installation

Using Skills CLI (Recommended)

Install to any supported coding agent using npx skills:

# Install to Claude Code (global)
npx skills add theclaymethod/deep-plan -g -a claude-code

# Install to multiple agents
npx skills add theclaymethod/deep-plan -g -a claude-code -a cursor -a codex

# Install to all detected agents
npx skills add theclaymethod/deep-plan -g

Manual Installation

# Clone the repo
git clone https://github.com/theclaymethod/deep-plan.git ~/dev/deep-plan

# Symlink to Claude Code skills directory
ln -s ~/dev/deep-plan ~/.claude/skills/deep-plan

# Or symlink to commands (for /deep-plan invocation)
ln -s ~/dev/deep-plan/SKILL.md ~/.claude/commands/deep-plan.md

Standalone Scripts

The Python utility scripts work independently:

# Find unaddressed annotations in a plan
python3 scripts/check_annotations.py .claude/plan.md

# Check task completion progress
python3 scripts/plan_progress.py .claude/plan.md

# Archive a completed plan
python3 scripts/archive_plan.py .claude/plan.md --name cursor-pagination --cleanup .claude/research.md

Usage

Start a Session

/deep-plan

Then describe what you want to build. The skill guides you through each phase.

The Workflow

Phase 1: Research. The agent deep-reads the relevant codebase and writes findings to .claude/research.md. You review it to verify the agent actually understood the system.

Phase 2: Plan. The agent writes a detailed implementation plan to .claude/plan.md with code snippets, file paths, and trade-offs.

Phase 2b: Interview (optional). If the plan has ambiguities the agent can't resolve from the codebase alone, it runs an interactive Q&A before handing the plan to you. Covers architectural choices (sync vs async, data modeling, migration strategy), API design, performance trade-offs, and UI/UX decisions. Answers get woven directly into the plan, not appended as a transcript. Saves annotation cycles by resolving open questions upfront.

Phase 3: Annotate. You open the plan in your editor and add inline notes directly into the document. Corrections, rejections, domain knowledge, scope cuts. Then tell the agent to update the plan. Repeat 1-6 times until you're satisfied.

Phase 4: Todo List. The agent adds a granular task breakdown with checkboxes to the plan.

Phase 5: Implement. The agent executes the entire plan, marking tasks complete as it goes. Runs typecheck continuously.

Phase 6: Feedback. You test, find issues, fire off terse corrections. The agent has full context so short messages work.

Phase 7: Archive. The completed plan moves to docs/completed-tasks/ for project history.

Example Annotations

Notes you'd add directly into plan.md:

use drizzle:generate for migrations, not raw SQL

no, this should be a PATCH, not a PUT

remove this section entirely, we don't need caching here

this is wrong, visibility should be on the list itself, not individual items

Example Implementation Prompt

implement it all. when you're done with a task or phase, mark it as completed
in the plan document. do not stop until all tasks and phases are completed.
do not add unnecessary comments or jsdocs, do not use any or unknown types.
continuously run typecheck to make sure you're not introducing new issues.

Project Structure

deep-plan/
├── SKILL.md                           # Main skill file (lean router)
├── README.md                          # This file
├── references/
│   ├── phase-1-research.md            # Research phase instructions
│   ├── phase-2-plan.md                # Planning phase instructions
│   ├── phase-3-annotate.md            # Annotation cycle instructions
│   ├── phase-4-todo.md                # Todo list phase instructions
│   ├── phase-5-implement.md           # Implementation phase instructions
│   ├── phase-6-feedback.md            # Feedback phase instructions
│   ├── phase-7-archive.md             # Archive phase instructions
│   └── annotation-guide.md            # How to write effective annotations
├── scripts/
│   ├── check_annotations.py           # Find unaddressed user notes
│   ├── plan_progress.py               # Task completion progress (X/Y)
│   └── archive_plan.py                # Move plan to docs/completed-tasks/
└── assets/
    └── templates/
        ├── research-template.md       # Skeleton for research output
        └── plan-template.md           # Skeleton for plan output

Supported Agents

This skill follows the Agent Skills specification and works with:

• Claude Code
• Cursor
• Codex
• OpenCode
• Cline
• Roo Code
• And 35+ other agents

Philosophy

Most developers type a prompt, sometimes use plan mode, fix the errors, repeat. The results fall apart for anything non-trivial.

This workflow fixes that by separating thinking from typing:

• Research prevents ignorant changes (the agent understands the system before proposing anything)
• The plan prevents wrong changes (every decision is explicit and reviewable)
• The annotation cycle injects your judgement (product priorities, domain knowledge, trade-offs)
• The implementation command lets the agent run without interruption once every decision is made

Three rounds of "I added notes, update the plan" can turn a generic implementation plan into one that fits the existing system exactly.

Credit

This workflow is based on How I Use Claude Code by Boris Tane.

Requirements

• Python 3.8+
• Any supported coding agent

License

MIT

Annotation Guide

How to write effective inline annotations in plan.md.

Quick Rules

1. Write notes directly in the plan document where the issue is 2. Be as terse or as verbose as the correction requires 3. Don't worry about formatting — just make it obvious it's a note 4. You can annotate anything: approach, code snippets, trade-offs, task ordering

Annotation Styles

Corrections (terse)

### API Layer

The endpoint should accept a PUT request with the full resource body.
not a PUT — use PATCH

Rejections

### Caching

We should add a Redis cache in front of the query to handle repeated lookups.
remove this section entirely, we don't need caching here

Domain Knowledge

### Migrations

We'll write a raw SQL migration to add the column.
use drizzle:generate for migrations, not raw SQL

Redirections

### Schema Changes

Add a `visibility` field to each item in the list.
this is wrong — visibility should be on the list itself, not individual items.
when a list is public, all items are public. restructure this section.

Constraints

### Refactor

We'll update the function signatures to accept the new parameter.
the signatures of these three functions should not change.
the caller should adapt, not the library.

Scope Cuts

### Phase 3: Download Feature

- [ ] Add download button to list view
- [ ] Generate CSV export

remove this phase, I don't want to implement this now

Tips

• Point at the exact spot where the issue is — don't describe location in prose
• Two words is fine if that's all it takes: "not optional"
• For code-level corrections, paste the code shape you expect
• If you're unsure about an approach, write your concern as a question: "should this handle the case where the list is empty?"

Phase 1: Research

Deep-read the relevant codebase. Surface-level skimming is not acceptable.

Process

1. Read every file in the relevant module/folder — not just entry points 2. Trace data flows, understand side effects, identify implicit contracts 3. Note existing patterns: caching layers, ORM conventions, shared utilities, API signatures 4. Write findings to .claude/research.md using the template at assets/templates/research-template.md

What the Research Document Must Cover

• What the system does and how
• Key abstractions and their responsibilities
• Data flow through the system
• Existing patterns that new code must respect
• Edge cases, invariants, and implicit assumptions
• File paths for every major component discussed

Depth Signals

Without explicit depth signals, the tendency is to skim — read a function signature and move on. The research must go deeper:

• Read function bodies, not just signatures
• Follow calls across files to understand the full chain
• Check how errors propagate
• Look at what's cached, what's lazy-loaded, what's eager
• Note any implicit ordering dependencies

Stop Condition

The document should be detailed enough that the user can verify you actually understood the system. If you can't explain why something is done a certain way, you haven't read deeply enough.

Example Prompts

read this folder in depth, understand how it works deeply, what it does and all
its specificities. when that's done, write a detailed report of your learnings
and findings in .claude/research.md

study the notification system in great details, understand the intricacies of it
and write a detailed .claude/research.md document with everything there is to
know about how notifications work

go through the task scheduling flow, understand it deeply and look for potential
bugs. there definitely are bugs in the system as it sometimes runs tasks that
should have been cancelled. keep researching the flow until you find all the
bugs, don't stop until all the bugs are found. when you're done, write a
detailed report of your findings in .claude/research.md

Phase Exit

Write .claude/research.md and tell the user it's ready for review. Do NOT proceed to planning until the user says to.

Phase 2: Plan

After the user reviews research.md, write a detailed implementation plan to .claude/plan.md using the template at assets/templates/plan-template.md.

What the Plan Must Include

• Detailed explanation of the approach
• Code snippets showing the actual changes (not pseudocode)
• File paths that will be modified or created
• Considerations and trade-offs
• How the changes integrate with existing patterns found in research

Rules

• Base the plan on the actual codebase. Read source files before proposing changes. Never design in a vacuum.
• When the user provides reference code from open source or other projects, use it as a concrete model — not vague inspiration.
• Every code snippet must reference a real file path in the project.
• If a change touches an existing function, show the before and after.

Example Prompts

I want to build a new feature <name and description> that extends the system to
perform <business outcome>. write a detailed .claude/plan.md document outlining
how to implement this. include code snippets

the list endpoint should support cursor-based pagination instead of offset.
write a detailed .claude/plan.md for how to achieve this. read source files
before suggesting changes, base the plan on the actual codebase

Optional: Interview

After writing the initial plan, if ambiguities remain that would waste annotation cycles, run an interview before handing the plan to the user.

When to run it:

• Multiple valid architectural approaches exist (e.g., sync vs async, polling vs webhooks, denormalize vs join)
• Data modeling decisions that depend on access patterns or scale expectations the codebase doesn't reveal
• API design choices: endpoint shape, auth strategy, versioning, error contract
• The feature involves UI/UX decisions you can't infer from the codebase
• Migration or backwards-compatibility strategy is unclear (big-bang vs incremental, feature flags)
• Performance or consistency trade-offs where the right answer depends on product context (eventual consistency OK? acceptable latency?)
• Business logic edge cases research couldn't answer (user intent, product priorities, failure modes)
• The plan contains explicit open questions or "TBD" sections

When to skip it:

• The plan is straightforward and well-scoped
• The user already provided detailed requirements
• Decisions can be confidently inferred from existing codebase patterns

How to run it:

1. Read the plan and identify every ambiguity, open question, assumption, or decision point where the user's input would change the approach. 2. Group related questions together. Prioritize questions where the answer would significantly change the implementation — skip anything obvious or inferable from the codebase. 3. Ask 2-4 questions at a time using AskUserQuestion. Questions should be specific and non-obvious. Bad: "What database should we use?" Good: "The notification queries will fan out per-user — should we denormalize into a per-user table for read speed, or keep the normalized schema and add an index?" 4. Continue interviewing until all ambiguities are resolved. Typically 2-4 rounds. 5. Integrate every answer directly into the relevant section of the plan — update the approach, code snippets, trade-offs, and task list accordingly. Don't append a Q&A transcript; weave the decisions into the plan as if they were always part of it.

Do NOT implement yet. The interview refines the plan — it doesn't replace the annotation cycle.

Phase Exit

End the plan with: "Ready for your review. Add any inline notes and I'll update the plan accordingly."

If the plan has unresolved ambiguities, suggest: "There are some open questions in the plan. Want me to interview you on them before you annotate?"

Do NOT implement yet.

Phase 3: Annotation Cycle

The core of the workflow. The user adds inline notes directly into .claude/plan.md, then sends you back to update it.

How It Works

1. User opens .claude/plan.md in their editor 2. User adds inline notes — corrections, rejections, constraints, domain knowledge 3. User tells you to address the notes 4. Read the plan, find all user annotations, update the document accordingly 5. Repeat until the user is satisfied (typically 1-6 rounds)

Detecting Annotations

User notes vary from two words to full paragraphs. Common patterns:

Run the annotation scanner to find them programmatically:

python3 <skill-path>/scripts/check_annotations.py .claude/plan.md

Rules

• Address every note. Don't skip any.
• After updating, confirm what you changed.
• Do NOT implement yet — this guard is non-negotiable until the user says to proceed.
• If a note is ambiguous, ask for clarification rather than guessing.
• Never remove user annotations yourself — the user removes them when satisfied.

Why This Phase Matters

The plan is shared mutable state. The user injects judgement that you don't have: product priorities, user pain points, engineering trade-offs, team conventions. Three rounds of annotation can transform a generic plan into one that fits perfectly into the existing system.

Example Prompts

I added a few notes to the document, address all the notes and update the
document accordingly. don't implement yet

Phase Exit

The user says they're satisfied with the plan, or explicitly asks to move to the todo list or implementation.

Phase 4: Todo List

Before implementation starts, add a granular task breakdown to the plan.

Process

1. Break the plan into phases and individual tasks 2. Add checkboxes to .claude/plan.md (e.g., - [ ] Task description) 3. Tasks should be atomic and independently verifiable 4. Group into logical phases

What Makes a Good Task

• Atomic: One thing per checkbox. "Add column and update model" is two tasks.
• Verifiable: You can confirm it's done without running the whole system. "Add visibility column to lists migration" is verifiable. "Make it work" is not.
• Ordered: Tasks within a phase should be in execution order.

Progress Tracking

During implementation, check progress with:

python3 <skill-path>/scripts/plan_progress.py .claude/plan.md

Example Prompt

add a detailed todo list to the plan, with all the phases and individual tasks
necessary to complete the plan - don't implement yet

Phase Exit

Do NOT implement yet. Wait for user approval of the task list.

Phase 5: Implementation

When the user says to implement, execute the entire plan without stopping.

Rules

1. Execute every task in the plan — do not cherry-pick 2. Mark each task complete (- [x]) in .claude/plan.md as you finish it 3. Do not stop until all tasks and phases are completed 4. Do not add unnecessary comments or jsdocs 5. Do not use any or unknown types 6. Run typecheck continuously to catch issues early, not at the end 7. If the project has a build command, run it at completion

Progress

The plan document is the source of truth for progress. The user should be able to glance at it at any time and see exactly where things stand.

Check progress programmatically:

python3 <skill-path>/scripts/plan_progress.py .claude/plan.md

Key Principle

Implementation should be boring. All creative decisions happened in the annotation cycles. By the time you implement, every decision should already be made.

Example Prompt

implement it all. when you're done with a task or phase, mark it as completed
in the plan document. do not stop until all tasks and phases are completed.
do not add unnecessary comments or jsdocs, do not use any or unknown types.
continuously run typecheck to make sure you're not introducing new issues.

Phase Exit

All tasks marked [x]. Build passes. Typecheck clean.

Phase 6: Feedback & Iteration

During implementation, the user shifts from architect to supervisor. Corrections become terse.

Accepting Corrections

The user has full context from the plan and session, so short corrections are enough:

• "You didn't implement the deduplicateByTitle function."
• "You built the settings page in the main app when it should be in the admin app, move it."
• "wider" / "still cropped" / "there's a 2px gap"

Reference-Based Corrections

When the user references existing code, read that reference before making changes:

• "this table should look exactly like the users table, same header, same pagination, same row density."
• "make the error handling match how we do it in the auth module"

This communicates all implicit requirements without spelling them out.

Reverts

If something goes wrong directionally, expect the user to revert via git and re-scope:

• "I reverted everything. Now all I want is to make the list view more minimal — nothing else."

Don't try to patch a bad approach. Start clean from the narrowed scope. Narrowing scope after a revert almost always produces better results than incremental fixes.

Selective Guidance

The user may cherry-pick from proposals or override technical choices:

• "for the first one, just use Promise.all; for the third one, extract it into a separate function; ignore the fourth and fifth ones"
• "remove the download feature from the plan, I don't want to implement this now"
• "the signatures of these three functions should not change, the caller should adapt"
• "use this library's built-in method instead of writing a custom one"

Phase 7: Archive

After all tasks are complete and verified, archive the plan.

Process

1. Ensure all tasks in the plan are marked [x] 2. Move .claude/plan.md to docs/completed-tasks/<slug>.md 3. Delete .claude/research.md — its purpose is served

Use the archive script:

python3 <skill-path>/scripts/archive_plan.py .claude/plan.md \
    --name <slug> \
    --cleanup .claude/research.md

The slug should be a short, descriptive name derived from the feature:

• cursor-pagination
• notification-system-refactor
• sortable-ids
• admin-settings-page

Why Archive

This builds a project history of completed work that's browsable by anyone on the team. Each archived plan is a complete record of what was built, why, and how.