deep-work_skill

Overview

This skill provides a disciplined "deep work" development workflow that separates research, planning, annotation, and implementation into distinct phases with persistent markdown artifacts. It enforces thorough codebase investigation and a written plan before any code is touched, reducing rework and integration surprises. Artifacts are stored under .claude/ so findings, plans, and task lists persist across the effort.

How this skill works

Begin with an exhaustive research pass of the target area and write a detailed report to .claude/research.md. Next, author a concrete implementation plan in .claude/plan.md with real code snippets, file paths, and trade-offs. Iterate via annotation cycles until the plan is approved, convert the plan into a granular todo checklist, then implement tasks sequentially while updating the plan file as work completes.

When to use it

• Starting any non-trivial feature that touches multiple files or systems
• Beginning a significant refactor or architecture change
• Investigating a difficult bug that requires end-to-end tracing
• When you want a strict "plan before coding" discipline
• Onboarding to an unfamiliar codebase area before making changes

Best practices

• Read implementations, not just signatures; trace data flows and edge cases
• Stop after research.md and get user review before writing a plan
• Plans must include real file paths and concrete code diffs, not pseudocode
• Keep tasks small and checkable; each task should be completable in one focused session
• Run type checks and linters after each implementation phase and update the checklist immediately

Example use cases

• Add a cross-cutting feature that requires database, API, and frontend changes
• Refactor a shared utility while preserving multiple integration points
• Triage and fix an intermittent production bug with unclear causes
• Adopt a reference implementation from another repo, adapting it to local patterns
• Prepare a safe rollout plan for a backwards-incompatible change