deep-work

name

deep-work

description

Structured development workflow that separates research, planning, and implementation into distinct phases with persistent markdown artifacts. Use when starting any non-trivial feature, refactor, bug investigation, or codebase change. Trigger on: "deep work", "research and plan", "plan before coding", "write a plan", "research this codebase", "don't code yet", "understand then implement", or when the user wants a disciplined approach to a complex task. Also use when the user says "research", "plan", "annotate", "implement the plan", or references research.md/plan.md artifacts.

Deep Work

Structured workflow that separates thinking from typing. Never write code until a written plan has been reviewed and approved.

Workflow Overview

Research → Plan → Annotate (repeat 1-6x) → Todo List → Implement → Feedback

All artifacts persist as markdown files in .claude/ (not the project root).

Phase 1: Research

Deeply read the relevant codebase before doing anything else. Write findings to .claude/research.md.

How to research:

1. Read every file in the target area — not just signatures, but implementations, edge cases, error handling
2. Trace data flows end-to-end
3. Identify existing patterns, conventions, utilities, and caching layers
4. Note integration points with other parts of the system
5. Write a detailed report to .claude/research.md

Research depth signals: Read deeply. Understand intricacies. Go through everything. Surface-level reading is not acceptable. Continue until you have a thorough understanding.

Template: See references/research-template.md for the research document structure.

Critical rule: Stop after writing research.md. Do not proceed to planning until the user has reviewed the research and confirmed it's accurate.

Phase 2: Plan

Write a detailed implementation plan to .claude/plan.md. Base the plan on the actual codebase — read source files before suggesting changes.

Plan contents:

• Explanation of the approach and rationale
• Code snippets showing actual changes (not pseudocode)
• File paths that will be modified or created
• Considerations and trade-offs
• Things explicitly not being changed and why

Template: See references/plan-template.md for the plan document structure.

Reference implementations: If the user provides reference code from other projects, study it and adapt the approach to fit the current codebase's patterns.

Critical rule: End the plan with "Ready for your review. Add inline notes directly to .claude/plan.md and tell me when to address them." Do not implement.

Phase 3: Annotation Cycle

The user adds inline notes directly into plan.md. When they say "address my notes" or similar:

1. Read .claude/plan.md thoroughly, finding all user annotations
2. User annotations are any text that wasn't in your original plan — look for corrections, questions, overrides, and constraints
3. Address every single annotation: update sections, remove rejected approaches, incorporate domain knowledge
4. Remove the annotation text itself after addressing it (keep the plan clean)
5. End with: "All notes addressed. Review again or say 'add the todo list' when satisfied."

Critical rule: Do not implement. The phrase "don't implement yet" is a hard constraint. Repeat the annotation cycle until the user explicitly approves.

Phase 4: Todo List

When the user approves the plan, add a granular task checklist to .claude/plan.md:

## Tasks

### Phase 1: [Phase Name]
- [ ] Task 1 — specific, actionable description
- [ ] Task 2 — specific, actionable description

### Phase 2: [Phase Name]
- [ ] Task 3 — specific, actionable description
- [ ] Task 4 — specific, actionable description

Each task should be small enough to complete in one focused step. Include all phases needed to fully implement the plan.

Critical rule: Do not implement yet. Wait for user confirmation to begin.

Phase 5: Implementation

When the user says "implement" or "go":

1. Execute every task in the plan sequentially
2. After completing each task, update .claude/plan.md — change - [ ] to - [x]
3. Do not stop until all tasks are completed
4. Run the project's type checker / linter after each phase to catch issues early
5. Do not add unnecessary comments, docstrings, or type workarounds (any, unknown)

Code quality rules during implementation:

• No unnecessary comments or jsdocs
• No any or unknown types (TypeScript projects)
• Run typecheck/lint continuously
• Follow existing codebase patterns exactly

Phase 6: Feedback

During implementation, the user may provide terse corrections. These are sufficient because full context exists in the plan and session:

• "You missed the dedup function" → implement what was missed
• "Move this to the admin app" → relocate as directed
• "Wider" / "2px gap" / "still cropped" → adjust and re-check
• "Make it look like the users table" → read that reference, match it exactly

On reverts: If the user says "I reverted everything" — re-read the current file state, narrow scope to exactly what they specify, and re-implement cleanly.

Prompt Reference

See references/prompts.md for ready-to-use prompts for each phase that the user can copy and adapt.