AGENTS/.pi/gsd/workflows/add-todo.md

Context (pre-injected)

Todo text:

State:

Capture an idea, task, or issue that surfaces during a GSD session as a structured todo for later work. Enables "thought → capture → continue" flow without losing context.

<required_reading> Read all files referenced by the invoking prompt's execution_context before starting. </required_reading>

Load todo context:

Extract from init JSON: commit_docs, date, timestamp, todo_count, todos, pending_dir, todos_dir_exists.

Ensure directories exist:

mkdir -p .planning/todos/pending .planning/todos/done

Note existing areas from the todos array for consistency in infer_area step.

**With arguments:** Use as the title/focus. - `/gsd-add-todo Add auth token refresh` → title = "Add auth token refresh"

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

Infer area from file paths:

Path pattern	Area
src/api/*, api/*	api
src/components/*, src/ui/*	ui
src/auth/*, auth/*	auth
src/db/*, database/*	database
tests/*, __tests__/*	testing
docs/*	docs
.planning/*	planning
scripts/*, bin/*	tooling
No files or unclear	general

Use existing area from step 2 if similar match exists.

```bash # Search for key words from title in existing todos grep -l -i "[key words from title]" .planning/todos/pending/*.md 2>/dev/null || true ```

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

Use values from init context: `timestamp` and `date` are already available.

Generate slug for the title:

slug=$(pi-gsd-tools generate-slug "$title" --raw)

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

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

## Problem

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

## Solution

[approach hints or "TBD"]

If `.planning/STATE.md` exists:

1. Use todo_count from init context (or re-run init todos if count changed)
2. Update "### Pending Todos" under "## Accumulated Context"

Commit the todo and any updated state:

pi-gsd-tools commit "docs: capture todo - [title]" --files .planning/todos/pending/[filename] .planning/STATE.md

Tool respects commit_docs config and gitignore automatically.

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

``` Todo saved: .planning/todos/pending/[filename]

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

---

Would you like to:

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

</step>

</process>

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