Todo

docs/todo.md is the per-repo task inbox.

Core Rule

Every task must be executable by a fresh agent with no session context. Self-contained: current behavior, expected behavior, and a verify step you watched fail once on an input where it must fail. If a task needs a decision the user hasn't made, AskUserQuestion before writing it down (AskUserQuestion is Claude Code's question tool; other harnesses ship their own native tool: opencode's question, gemini-cli's ask_user, Codex CLI's request_user_input. Use it if present, else fall back to a plain numbered message). Never park open questions inside a task.

Tasks say what needs to change and, sometimes, how. Never where in the code: no file:line into source, no path that only locates code. A path stays where the file is the task's subject (an instruction file, a hook, a config the task edits), since there the path is the identity.

State observed behavior as fact; label attributed causes as hypotheses. A task's "current behavior" is what you saw or reproduced. Any "why" you did not verify (an engine's timing, an API's state model, a component's intent) must read as a hypothesis (hypothesis:, suspected:), never as fact. Baking an unverified root cause into a task sends the executing agent to fix the wrong thing (a retry built on an inferred "the API hasn't synced" missed that the API never stored the data at all). If the cause is load-bearing for the fix, the verify step must confirm it first against the vendor source (swagger/docs/code) or a repro before the fix is built on it.

Size tasks by scope. Combine small related nits into one task; split anything too big for a single reviewable change into independent tasks. The unit is "one agent, one clean commit".

Two Formats, Picked by Source

Audit Findings / Bugs -> Punch-List

For audit results, contract violations, bug reports:

# <audit name> punch-list

<one-line provenance: what was audited against what, date>

## <component / feature area>

- [ ] <current behavior> -> <required behavior>. <optional how. ordering note if other items cascade from it>

• Group by component or feature area, not by severity.
• Note cascade order explicitly ("fix first: X findings depend on it").

Feature Ideas / Specs -> Checkbox Spec

For new features, enhancements, raw idea notes:

## <N>. <feature title>

<one-line intent if the title doesn't carry it>

### <surface: Backend / Frontend / TUI / CLI / Schema>
- [ ] <concrete, verifiable step>

• Number tasks; subsection per surface touched; one reviewable change per checkbox.

Normalizing Raw Notes

When the user dumps loose notes ("inconsistent cursor..", "remove j/k"):

1. Read the relevant code first. Resolve each note to specific files and current behavior.
2. Ask clarifying questions for anything ambiguous (batch them, don't trickle).
3. Rewrite as tasks in the matching format above. The original note text can be dropped once the task captures it fully.

Resolving

• docs/todo.md holds OPEN work only. A landed item gets propagated to where it can't rot (a test that fails when the behavior changes, else the owning docs/ page or CLAUDE.md), then deleted from the list instead of left as a checked-off record. A ship narrative parked in the backlog drifts against the code it describes; nothing re-reads it to notice.
• A blocked task's gate names the OBSERVABLE it waits on, never the event. One written as "has the export arrived" cleared on delivery across two sessions and the delivered file was useless both times, because what was actually needed was a populated download link inside it. Phrase every gate as a check someone can run and get a yes/no from.
• Never delete an unresolved or in-progress task without the user saying so. Deletion is reserved for a task you have confirmed landed and propagated; it is never a way to prune work you chose to skip.
• When asked to "resolve the todo", route execution through your multi-task runner or workflows (one task each); this skill only owns the file.