Managing Todos

Managing Todos

Lightweight todo tracking using markdown files. Todos capture things noticed during a session to tackle later.

Directory & Customization

Default directory: docs/todos/, archived todos go to docs/todos/done/.

Projects can override defaults in their CLAUDE.md:

## Todos
- directory: .todos/
- statuses: open, in-progress, blocked, done, wont-fix

The todo.sh script in this skill directory reads ## Todos from CLAUDE.md automatically.

The Script

Always use ~/.claude/skills/managing-todos/todo.sh for all operations. It validates statuses, priorities, sets the correct created date, and respects CLAUDE.md overrides.

# Create
todo.sh create -t "Fix hardcoded URL" -p high --tags "refactor,config" -d "Move API URL to env var"

# Multiline description
todo.sh create -t "Fix auth flow" -p high -d $'First line.\nSecond line.\nThird line.'

# List / Filter
todo.sh list                          # all active todos
todo.sh list -s open -p high          # open + high priority
todo.sh list --tag frontend           # by tag

# Update
todo.sh update "hardcoded-url" -s in-progress
todo.sh update "hardcoded-url" -p low --tags "config,cleanup"

# Archive (sets status=done + moves to done/ subfolder)
todo.sh archive "hardcoded-url"

Run todo.sh with no args for full usage.

File matching is partial — "hardcoded-url" matches 2026-03-25-fix-hardcoded-url.md.

File Format

Filename: YYYY-MM-DD-short-description.md (auto-generated by script)

Frontmatter:

• status — open, in-progress, done (or project-custom)
• priority — low, medium, high
• created — ISO date (auto-set by script)
• tags — YAML list

List Output Format

## Open Todos (2)

**[high] Add error boundaries** (2026-03-15) — frontend, error-handling
  No error boundaries in place. A crash takes down the whole page.

**[medium] Update deprecated deps** (2026-03-18) — dependencies
  Replace node-sass, request, moment with modern alternatives.

Auto-Detection

When you notice something during a session that is unrelated to the current task and worth capturing:

You MUST ask the user before creating a todo. Example:

I noticed [issue]. Want me to create a todo for this?

Never silently create todos. The user may already be aware, may disagree on priority, or may not want it tracked.

Only skip confirmation when the user explicitly says something like "todo: fix X later" or "add a todo for Y" — that's direct instruction, not auto-detection.

Common Mistakes

• Creating todos without the script (bypasses validation)
• Creating todos without asking when auto-detecting
• Archiving by deleting instead of using todo.sh archive