Adding Todos

/kata:add-todo

Enables "thought → capture → continue" flow without losing context or derailing current work.

Note existing areas for consistency in infer_area step.

Without arguments: Analyze recent conversation to extract:

• The specific problem, idea, or task discussed
• Relevant file paths mentioned
• Technical details (error messages, line numbers, constraints)

Formulate:

• title: 3-10 word descriptive title (action verb preferred)
• problem: What's wrong or why this is needed
• solution: Approach hints or "TBD" if just an idea
• files: Relevant paths with line numbers from conversation

Use existing area from step 2 if similar match exists.

If potential duplicate found:

1. Read the existing todo
2. Compare scope

If overlapping, use AskUserQuestion:

• header: "Duplicate?"
• question: "Similar todo exists: [title]. What would you like to do?"
• options:
  • "Skip" — keep existing todo
  • "Replace" — update existing with new context
  • "Add anyway" — create as separate todo

Generate slug from title (lowercase, hyphens, no special chars).

Write to .planning/todos/pending/${date_prefix}-${slug}.md:

---
created: [timestamp]
title: [title]
area: [area]
files:
  - [file:lines]
---

## Problem

[problem description - enough context for future Claude to understand weeks later]

## Solution

[approach hints or "TBD"]

1. Count todos: ls .planning/todos/pending/*.md 2>/dev/null | wc -l
2. Update "### Pending Todos" under "## Accumulated Context"

Check planning config:

COMMIT_PLANNING_DOCS=$(cat .planning/config.json 2>/dev/null | grep -o '"commit_docs"[[:space:]]*:[[:space:]]*[^,}]*' | grep -o 'true\|false' || echo "true")
git check-ignore -q .planning 2>/dev/null && COMMIT_PLANNING_DOCS=false

If COMMIT_PLANNING_DOCS=false: Skip git operations, log "Todo saved (not committed - commit_docs: false)"

If COMMIT_PLANNING_DOCS=true (default):

git add .planning/todos/pending/[filename]
[ -f .planning/STATE.md ] && git add .planning/STATE.md
git commit -m "$(cat <<'EOF'
docs: capture todo - [title]

Area: [area]
EOF
)"

Confirm: "Committed: docs: capture todo - [title]"

[title] Area: [area] Files: [count] referenced

Would you like to:

1. Continue with current work
2. Add another todo
3. View all todos (/kata:check-todoss)

</step>

</process>

<output>
- `.planning/todos/pending/[date]-[slug].md`
- Updated `.planning/STATE.md` (if exists)
</output>

<anti_patterns>
- Don't create todos for work in current plan (that's deviation rule territory)
- Don't create elaborate solution sections — captures ideas, not plans
- Don't block on missing information — "TBD" is fine
</anti_patterns>

<success_criteria>
- [ ] Directory structure exists
- [ ] Todo file created with valid frontmatter
- [ ] Problem section has enough context for future Claude
- [ ] No duplicates (checked and resolved)
- [ ] Area consistent with existing todos
- [ ] STATE.md updated if exists
- [ ] Todo and state committed to git
</success_criteria>