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. 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: