research-plan-todo

name

research-plan-todo

description

Boris Tane's structured 3-phase workflow for non-trivial tasks: Research → Plan → Todo → Implement. Use when starting a new feature, refactoring, bug investigation, or any task where you want to plan deeply before coding. Creates research.md, plan.md, and todo.md as shared artifacts for iterative refinement. DO NOT write code until the plan is explicitly approved. Trigger when user says "研究して", "計画を立てて", "research and plan", "plan before coding", or starts a complex task that benefits from upfront analysis.

Implement Boris Tane's "Read deeply, write a plan, annotate the plan until it's right, then let Claude execute the whole thing without stopping" workflow. The three markdown files serve as shared mutable state between Claude and the developer, replacing ambiguous chat-based instructions with concrete, reviewable artifacts.

<core_principle> NEVER write implementation code until the plan is explicitly approved by the user. Each phase produces a document for human review. The annotation cycle is the heart of the workflow. </core_principle>

Deep codebase understanding before any planning Use emphatic language: "deeply", "in great details", "thoroughly". Surface-level reading leads to planning failures. Read all relevant files, not just entry points Trace data flows and dependency chains Identify existing patterns, conventions, and constraints Note potential conflicts or risks with the requested change Find reference implementations in the codebase if available Write findings to research.md in the working repository ## Task Overview [One-sentence description of what needs to be done]

  ## Codebase Understanding
  ### Relevant Files
  - [file]: [what it does, why it's relevant]

  ### Current Architecture
  [How the relevant parts currently work]

  ### Data Flows
  [How data moves through the affected system]

  ### Existing Patterns
  [Conventions and patterns to follow]

  ### Constraints and Risks
  [Technical constraints, potential breaking changes, edge cases]

  ### Reference Implementations
  [Similar implementations in codebase or linked open source examples]
</output_format>
<completion_signal>
  Present research.md summary to user and ask:
  "research.md を作成しました。内容を確認して問題なければ計画フェーズに進みます。修正点があればお知らせください。"
</completion_signal>

Implementation plan creation with iterative annotation cycle Base plan on research.md findings - never plan without research Structure plan as phases with clear boundaries Include specific file paths and function names from research Make scope explicit - list what is and is NOT included Write plan to plan.md in the working repository The core refinement loop. Repeat 1-6 times until plan is right. Open plan.md in editor and add inline comments/notes directly in the document "plan.md にメモを追加しました。すべてのメモに対応してドキュメントを更新してください。実装はまだしないでください。" Address every annotation, update plan.md, do NOT write any implementation code Add domain knowledge: "マイグレーションは drizzle:generate を使うこと" Reject approach: "このセクションは削除してください" Fix specification: "PUT ではなく PATCH を使うこと" Add constraint: "既存テストを壊さないこと" Scope control: "v1 ではここまで。この機能は含めない" User explicitly approves: "これでいい" / "実装してください" / "LGTM" ## Goal [What this plan achieves and why]

  ## Scope
  ### In Scope
  - [explicit list of what will be done]
  ### Out of Scope
  - [explicit list of what will NOT be done]

  ## Approach
  [High-level strategy and key decisions with rationale]

  ## Phases
  ### Phase 1: [Name]
  **Objective**: [What this phase achieves]
  **Files**: [Specific files to modify/create]
  **Changes**: [What will change and how]

  ### Phase 2: [Name]
  ...

  ## Technical Decisions
  | Decision | Choice | Rationale |
  |----------|--------|-----------|
  | [topic]  | [what] | [why]     |

  ## Risks and Mitigations
  - [risk]: [mitigation]
</output_format>
<completion_signal>
  After each annotation cycle update, ask:
  "plan.md を更新しました。追加のメモがあれば plan.md に記入してください。問題なければ「実装してください」とお知らせください。"
</completion_signal>

Granular task breakdown that serves as progress tracker during implementation Create AFTER plan.md is approved, BEFORE implementation starts Decompose each plan phase into atomic, checkable tasks Tasks should be small enough to complete in one focused action Order tasks to minimize broken states (tests pass at each step if possible) Write todo.md to the working repository ## Todo: [Feature/Task Name]

  ### Phase 1: [Name]
  - [ ] [Specific atomic task]
  - [ ] [Specific atomic task]
  - [ ] [Specific atomic task]

  ### Phase 2: [Name]
  - [ ] [Specific atomic task]
  - [ ] [Specific atomic task]

  ### Verification
  - [ ] All existing tests pass
  - [ ] [Feature-specific verification]
  - [ ] [Edge case verification]
</output_format>

Execution without strategy changes Only after todo.md is created and user confirms to proceed "すべてのタスクを実装してください。タスクまたはフェーズが完了したら plan.md と todo.md の該当項目を完了済みにマークしてください。すべてのタスクが完了するまで止まらないでください。" Mark tasks complete in todo.md as you finish them Mark phases complete in plan.md when all phase tasks are done Do not change the strategy mid-implementation - that requires a new annotation cycle If blocked, note the blocker in plan.md and continue with unblocked tasks Run type checks and tests after each phase completes

<file_locations> Create all files in the working repository root (or a .claude/ subdirectory if preferred) research.md, plan.md, todo.md are project artifacts, not temporary files These files should be gitignored or committed based on team preference </file_locations>

<quality_boosters> Providing open source examples of similar features dramatically improves plan quality. Ask: "このような実装の参考例はありますか？" when research reveals no internal references. Use "deeply" and "in great details" explicitly. Vague research instructions produce surface-level findings. Actively evaluate each plan item. Remove anything that isn't essential for the current task. The best plan maximizes removed scope, not added features. Run Research → Planning → Implementation in one session. Context is preserved through automatic summarization; starting fresh loses research findings. </quality_boosters>

NEVER write implementation code before plan.md is approved NEVER skip the research phase - planning without understanding leads to rework NEVER implement during annotation cycles - only update plan.md Always create todo.md before starting implementation Repeat annotation cycle until user explicitly approves Keep plan.md updated with completion status during implementation Make scope explicit in plan.md - what is NOT included is as important as what is

<anti_patterns> Starting to write code while still discussing the approach Complete the full annotation cycle until plan is approved, then create todo.md, then implement Reading only entry points or high-level files Trace full data flows, read all relevant files, find existing patterns Including "nice to have" features in the plan Actively remove non-essential items; minimal scope = faster, safer implementation Discussing plan changes in chat instead of annotating plan.md Add inline annotations directly to plan.md; then ask Claude to address them Not documenting constraints and potential breaking changes in research.md Explicitly identify risks in research.md and address them in plan.md </anti_patterns>

<best_practices> Research deeply before planning - the quality of research determines the quality of the plan Use inline annotations in plan.md for all plan changes, not chat messages Include reference implementations when available to improve plan quality Make scope explicit - list both what IS and IS NOT included Keep all three files updated throughout the workflow as living documents </best_practices>

<related_skills> Use TDD during implementation phase for test-first development Apply Tidy First before behavioral changes during implementation Commit after each phase completion with WHY-focused messages Use for deeper requirements analysis if task requirements are unclear </related_skills>