gpd-add-todo

name	gpd-add-todo
description	Capture idea or task as todo from current research conversation context
argument-hint	[optional description]
context_mode	projectless
allowed-tools	["read_file","write_file","shell","ask_user"]

<codex_runtime_notes> Codex shell compatibility:

• When shell steps call the GPD CLI, use /Users/charlie/.gpd/venv/bin/python -m gpd.runtime_cli --runtime codex --config-dir ./.codex --install-scope local instead of the ambient gpd on PATH.
• If you intentionally need the repo environment, keep the runtime pin: GPD_ACTIVE_RUNTIME=codex uv run gpd .... </codex_runtime_notes>

Capture an idea, task, or issue that surfaces during a GPD session as a structured todo for later work.

Routes to the add-todo workflow which handles:

• Directory structure creation
• Content extraction from arguments or conversation
• Area inference from file paths
• Duplicate detection and resolution
• Todo file creation with frontmatter
• STATE.md updates
• Git commits

Typical physics research todos include:

• "Check limiting case where coupling constant vanishes"
• "Derive equation of motion from the effective Lagrangian"
• "Run simulation with doubled grid resolution for convergence check"
• "Compare with reference [N] Table III values"
• "Verify dimensional consistency of Eq. (17)"
• "Write section on methodology and approximation scheme"
• "Plot dispersion relation for three parameter regimes"
• "Compute error bars using jackknife resampling"
• "Check that result reduces to known expression in non-relativistic limit"
• "Add physical interpretation of the imaginary part of the self-energy"

<execution_context> @.gpd/STATE.md

Capture an idea, task, or issue that surfaces during a GPD session as a structured todo for later work. Enables "thought -> capture -> continue" flow without losing context. Typical physics research todos include: a subtlety to check, a reference to look up, an alternative approach to explore, a numerical test to run, or a derivation step to verify.

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

Load todo context:

INIT=$(/Users/charlie/.gpd/venv/bin/python -m gpd.runtime_cli --runtime codex --config-dir ./.codex --install-scope local init todos)
if [ $? -ne 0 ]; then
  echo "ERROR: gpd initialization failed: $INIT"
  # STOP — display the error to the user and do not proceed.
fi

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

Note: add-todo works even without a project (creates .gpd/todos/ standalone). No project_exists gate needed — todos can be created independently.

Ensure directories exist:

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

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

**With arguments:** Use as the title/focus. - `$gpd-add-todo Check unitarity of S-matrix at two loops` -> title = "Check unitarity of S-matrix at two loops"

Without arguments: Analyze recent conversation to extract:

• The specific problem, idea, or task discussed
• Relevant file paths or notebook sections mentioned
• Technical details (equations, parameter values, limits, 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 and content:

Path pattern / content	Area
derivations/*, analytical/*	analytical
numerics/*, simulations/*, src/*	numerical
references/*, bibliography/*	literature
data/*, results/*, plots/*	data-analysis
tests/*, validation/*	validation
notebooks/*	notebooks
.gpd/*	planning
scripts/*, tools/*	tooling
Equation/formalism discussion	formalism
Symmetry/consistency checks	consistency
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]" .gpd/todos/pending/*.md 2>/dev/null ```

If potential duplicate found:

1. Read the existing todo
2. Compare scope

Platform note: If ask_user is not available, present these options in plain text and wait for the user's freeform response.

If overlapping, use ask_user:

• 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=$(/Users/charlie/.gpd/venv/bin/python -m gpd.runtime_cli --runtime codex --config-dir ./.codex --install-scope local --raw slug "$title")
todo_file=".gpd/todos/pending/${date}-${slug}.md"

Write to ${todo_file}:

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

## Problem

[problem description - enough context for a future AI session to understand weeks later]

## Solution

[approach hints or "TBD"]

If `.gpd/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:

PRE_CHECK=$(/Users/charlie/.gpd/venv/bin/python -m gpd.runtime_cli --runtime codex --config-dir ./.codex --install-scope local pre-commit-check --files "${todo_file}" .gpd/STATE.md 2>&1) || true
echo "$PRE_CHECK"

/Users/charlie/.gpd/venv/bin/python -m gpd.runtime_cli --runtime codex --config-dir ./.codex --install-scope local commit "docs: capture todo - ${title}" --files "${todo_file}" .gpd/STATE.md

Tool respects commit_docs config and gitignore automatically.

Confirm: "Committed: docs: capture todo - ${title}"

``` Todo saved: ${todo_file}

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

---

Would you like to:

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

</step>

</process>

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

<!-- [end included] -->

</execution_context>

<process>
**Follow the add-todo workflow** from `@./.codex/get-physics-done/workflows/add-todo.md`.

The workflow handles all logic including:

1. Directory ensuring
2. Existing area checking
3. Content extraction (arguments or conversation)
4. Area inference
5. Duplicate checking
6. File creation with slug generation
7. STATE.md updates
8. Git commits
   </process>