Files
claude-config/rules/todo-items.md
T

10 KiB
Raw Blame History

paths
paths
**/todo.md

Todo items (todo.md)

  • A plan is mandatory in every project, and a plan kept as todo.md has the shape rank_todo.py --help shows, which ~/.claude/bin/rank_todo.py checks and ranks; its --help shows a valid file. A plan in a Jira epic is read from the epic's open child issues. todo-item add files an item there as a new child issue, and todo-item finish moves an item's issue to done. todo-item --help says what edit and move change there. Below, todo.md means a plan kept as a file, and "the plan" either kind. ## Scoring holds the formula and the bar; ## Items is one table of every item; ## Details holds each item's detail under its ID. ## Renamed marks each renamed release with a line such as - 0.2.1 renamed to 0.3.0; rank_todo.py --help says what a mark does. Cite an item by its ID. The formula and bar are the project's own to tune.
  • File an item with ~/.claude/bin/todo-item add, and change one with todo-item edit or todo-item move. add and edit --detail read the item's detail from stdin, and all three commands rank the plan; todo-item --help shows the flags. todo-item finish <ID> --no-changelog drops an item no chunk built. Edit todo.md itself only for what todo-item has no command for: ## Scoring, ## Renamed, and reshaping an old table.
  • Order items only by score and the Blocked by column. An item's Blocked by cell lists the IDs of the items that must be done before it starts, such as 12, 14; rank_todo.py --help says how it ranks them. No text in todo.md outside the table orders items: where an item must go first, score it so, and say why in its detail.
  • Plan only on the project's rung or above. loop-claude's prompt tells you when you run below it. Below it, never score or re-score an item, move it between releases, split a milestone into items, delete an item under the bar, rewrite a filed item's tagline or detail, or choose or replace an item in docs/score-anchors.md. Draft each new item, each change to a filed item, and each change to the anchors, instead. Before your next commit, launch one subagent to apply the drafts, score them and set their release. Launch it on the rung CLAUDE.md's delegation rule gives a subagent that files or scores items. Keep the scores and releases it writes. For a security finding, launch it at once. Any rung may remove a finished item's row and detail, and score a delegated task's L. A subagent launched for another task leaves the plan alone.
  • An item's release allows the bump that semver read strictly asks for. An item that changes what exists needs a major, or before 1.0.0 a minor. One that only adds needs a minor, and a fix a patch.
  • Score an item when it is filed or edited. S, the size of the change, is a whole number from 1 to 10. Score L, E and I by the levels below, each level about ten times as likely, or as damaging, as the one below it. rank_todo.py writes R, the risk that the change creates serious bugs or issues: L + E + I − 2, at least 7 when I is 5 and at least 5 when I is 4, since a severe enough consequence outranks how unlikely it is. A task's L picks its worker's rung, and its E + I its reviewers' rung.
Level L — chance the change holds a defect E — chance the defect escapes I — damage, worst of availability, data, secrets, reach and reversibility
1 S 1–2, and nothing new a test or the gate fails on it one person's tooling or something cosmetic; a revert fixes it in minutes
2 S 3–5, in one component, a pattern the repo already has only review or a manual check sees it one feature or service degraded; a revert within the hour
3 one of: S 6 or more, several components, a new tool or pattern, live config or state nothing checks it before users hit it a service down, or every consumer affected; hours to restore
4 two or more of level 3's, or a rewrite of code with known defects — everything down, a backup restore, or a secret or PII exposed
5 — — irreversible: data lost for good, or a one-way door
  • I's reach counts every project and session that runs the change. A change to a hook or a tool that every session runs is I level 3, every consumer affected, even where one person uses it.
  • Name in Moves each goal in the goals file's ## Goals the item moves, and how far, from 1 to 10, judged by its value to the audience in ## Audience: 1.1 by 8, 1.2 by 5. Where the item moves code health, the goal in CLAUDE.md → "Shared goal", name it as in code health by 6, unless the goals file voids it. Name the most specific goal it moves, and a parent goal only for a move none of its sub-goals covers, never beside its own sub-goal. Name a maintain goal only where the item adds a test, a gate leg or a probe that fails where the goal breaks, or is a defect that restores it. For the test, gate leg or probe, the move is how much more confident the project becomes that the goal holds, judged against the confidence it already has: 9 or 10 where nothing yet shows the goal holds, about 5 where the item guards something new in an area mostly covered, 1 where it adds another way to check what is already checked. After one such item lands, judge the next against the new confidence. For a defect, the move is how much of the goal is broken. A change that only claims the goal doesn't move it. rank_todo.py --help says how it weighs each goal.
  • A table with C, A, G and Goals in place of L, E, I and Moves is in the old shape. Reshaping it is the project's only work until done, as CLAUDE.md → "Working loop" says, and rank_todo.py says how. Until then, A is the item's value to the audience and G its value to the goals it cites.
  • Score L, E and I against the project's anchors, and check every score against finished chunks. Guess the scores, then run ~/.claude/bin/score-outcomes <L> <E> <I> <S> in the project. It lists the finished items guessed nearest and the project's anchors, the shipped items its docs/score-anchors.md names for each level, each with what its chunk measured; then the median outcome at each guessed R and S, and how well L, E and I each order the chunks by review rounds and 🔴 findings, L by the share of chunks with a 🔴 instead where most hold none. Compare the item with each anchor in turn: is it more or less likely to hold a defect, to let one escape, or to do damage? Give it the level whose anchors it matches; where a level has no anchor, judge by the level's words in the table above. Set S to the value guessed for the finished items whose outcome matches what you expect of this one. Keep your guess when no listed item resembles the one you are scoring.
  • Anchor each level of L, E and I with two or three items the project shipped, in docs/score-anchors.md: a table whose Level column names a level, such as L 1, and whose Items column lists the anchors' IDs, such as 12, 14. Choose an L anchor whose chunk, as score-outcomes measured it, fits the level's words: its lines changed and the components it touched. Choose an E anchor by the level's words and the later fixes score-outcomes counts for its chunk, the defects that escaped it. Choose an I anchor by the level's words and what followed its release, since no tool measures I yet. Leave out a level no shipped item shows. Replace a level's anchors when the items scored at it turn out about ten times more likely, or ten times less likely, than its words say: to hold a defect, to let one escape, or to do damage.
  • Read the places the comprehension seats found hard before filing an item. ~/.claude/bin/larv-review places, run in the project, prints them. Where the item's change touches one, its detail says to make that place easier to read.
  • An item scoring under the bar is deleted, with every item that needs it, and a finding under the bar is not filed. The chunk's summary names each, with its score.
  • The Exempt cell keeps an item whatever its score: security for a security finding, defect for a 🔴 finding or an item that restores a maintain goal the project breaks today, question for a question only the human can answer, which ranks first in its release, decision for an item docs/decisions.md cites, owner for an item the human told you to keep, and, where no other reason fits, principle for a 🟡 finding against a file in the config's principles folder, whose item's detail names that principle. Every item docs/decisions.md cites carries one of these reasons.
  • A maintain goal vetoes an item that breaks it, whatever the item scores: redesign the item so it holds the goal, or drop it.
  • When you remove an item that no chunk built, title the commit Drop item <ID>: <why>, or Drop items 12, 14 and 15: <why> for several. Such an item was deleted under the bar, vetoed, superseded or moot; a finished item is not one. Without the title, score-outcomes credits the item with the work of the chunk that removed it, where that chunk changed more than todo.md.
  • Predict, in the detail of each item of the next release, what the item will touch. When you plan the next release, or file or move an item into it, give the item's detail a Touches: line, then one bullet per file the item will change. Each bullet names the file, then the parts of it the item will change: a function, a class or a section heading, or line ranges where the file has none of these. A path alone means the whole file. Read the code first; a prediction from the item's text alone misses. ~/.claude/bin/touch-predictions --help shows the spelling and how a part is named; a name that holds a backtick takes a longer run of backticks with a space inside each end, as a Markdown code span does. Mark a part (small) where the item changes only a few lines of it. (small) follows a part, never a bare path. A part is a name in backticks, or lines <first>-<last>. BANNED: - `bin/a.py` (small), - `README.md`: loop-claude's section (small). GOOD: - `bin/a.py`: `main` (small), - `README.md`: `## Tools` (small). Leave out the plan and the project's records, which every chunk writes. chunk-preflight reads the predictions to name the items that may start chunks at once, and touch-predictions record keeps each beside what its chunk touched. todo-item add, todo-item edit and rank_todo.py --check refuse a list touch-predictions cannot read.