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:

Read every file in the target area — not just signatures, but implementations, edge cases, error handling
Trace data flows end-to-end
Identify existing patterns, conventions, utilities, and caching layers
Note integration points with other parts of the system
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:

Read .claude/plan.md thoroughly, finding all user annotations
User annotations are any text that wasn't in your original plan — look for corrections, questions, overrides, and constraints
Address every single annotation: update sections, remove rejected approaches, incorporate domain knowledge
Remove the annotation text itself after addressing it (keep the plan clean)
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":

Execute every task in the plan sequentially
After completing each task, update .claude/plan.md — change - [ ] to - [x]
Do not stop until all tasks are completed
Run the project's type checker / linter after each phase to catch issues early
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.

deep-work