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

6.8 KiB
Raw Blame History

paths
paths
**/todo.md

Todo items (todo.md)

  • todo.md is mandatory in every project, in the shape rank_todo.py --help shows, which ~/.claude/bin/rank_todo.py checks and ranks; its --help shows a valid file. ## Scoring holds the formula and the bar; ## Items is one table of every item; ## Details holds each item's detail under its ID. Cite an item by its ID. The formula and bar are the project's own to tune.
  • 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 todo.md 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 achieve goal in README.md → ## 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. 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. Leave out every maintain goal, which vetoes, except on an item marked defect that restores it: name that goal, and how much of it is broken. 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. 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 or I anchor by the level's words and what followed its release, since no tool measures either 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 under ~/.claude/principles/, 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.