TodoWrite#

Route TODO checklists to the appropriate storage based on context, and enforce conversational/reporting discipline around TaskList items.

Routing Decision#

text

New TODO arrives
  ├─ Only needed this session → /wip (TaskCreate/TodoWrite)
  ├─ Persists beyond session → file (fix_plan.md, TODO.md)
  └─ Team-shared → issue (GitHub Issues)

Topics#

TopicStorageLifetimeTool / GuidesessionTaskCreate/TodoWriteSessionDelegation-only — this row routes to the /wip skill; todowrite does not implement session tracking itselffilefix_plan.md, TODO.mdWhile file existsWrite/EditissueGitHub IssuesPermanentgh issue createconversation-id—Always-onconversation-id.md — subject-prefix references in user-visible output. Enforced by resources/block-tasklist-id-in-conversation.sh (PreToolUse:AskUserQuestion, registered in settings.json)completion-report—Always-oncompletion-report.md — TaskUpdate completion format + file-change disclosurefix-plan-sync—Always-onfix-plan-sync.md — two-way sync between task medium and checklist mediumpriority-prefix—Always-onpriority-prefix.md — priority/order via subject prefix ( P{n}, PR-anchored, fix-* > P0)media-separation—On-demandmedia-separation.md — 3-layer model: tracking files vs RAG vs LLM Wikiclaude-taskTask JSON CLIPermanent / Standaloneclaude-task.md — standalone Python CLI tool ( claude-task.py) for managing Task JSON files directly from terminal shell

Skip exceptions#

TodoWrite can be skipped when:

• Running a single command (e.g., kubectl get, ls)
• A task with 2 or fewer trivial steps
• Information lookup only

AskUserQuestion can be skipped when:

• The user gave a clear directive
• The action is safe and reversible
• The general best practice is unambiguous

Session → /wip#

Current session task tracking is handled by the wip skill:

text

/wip    # Track session work with TodoWrite/TaskCreate

File-based TODO#

fix_plan.md (Ralph projects)#

markdown

## Pending

- [ ] Item 1 — description
- [ ] Item 2 — description

## Completed

- [x] Done item — (completed: 2026-04-03, commit abc1234)

Rules:

• Move to Completed section on completion + timestamp
• Mark blocked items with [BLOCKED] tag
• Mark skipped items with [SKIPPED] tag

TODO.md (General projects)#

markdown

# TODO

## High Priority
- [ ] Urgent item

## Normal
- [ ] Regular item

## Done
- [x] Completed item (2026-04-03)

Issue-based TODO#

Team-shared TODOs go to GitHub Issues:

bash

# Create issue (user approval required)
gh issue create --title "Item" --body "Description"

# List issues
gh issue list --label "todo"

Note: gh issue create only runs when user explicitly says "create an issue".

Routing Examples#

SituationRouteReason"Run this 5-step deploy"/wip (session)Session tracking is sufficient"Fix this bug later"file (fix_plan.md)Persists beyond session"Assign this to Jinju"issue (GitHub)Team sharing needed"Note this from the review"file (fix_plan.md)Outside current PR scope