Answer prose round 1: 0 🔴, 6 🟡 (0 misread); reword the help, docstrings, rule and item text

This commit is contained in:
2026-11-18 16:35:03 +01:00
parent 8f1d28f160
commit 1559dcd6c9
3 changed files with 5 additions and 5 deletions
+2 -2
View File
@@ -85,7 +85,7 @@ class FilePlan:
return ranked return ranked
def check(self) -> list[str]: def check(self) -> list[str]:
"""Why `rank_todo.py --check` fails on the file, empty when it passes: the file is not ranked, an item scores under the bar, or an item's `Touches:` list is one touch-predictions cannot read.""" """Why `rank_todo.py --check` fails on the file, empty when it passes: the file is not ranked, an item scores under the bar, or touch-predictions cannot read an item's `Touches:` list."""
texts = self.texts() texts = self.texts()
if isinstance(texts, Failure): if isinstance(texts, Failure):
return [texts.reason] return [texts.reason]
@@ -117,7 +117,7 @@ class FilePlan:
def unreadable_touches(todo: str) -> list[str]: def unreadable_touches(todo: str) -> list[str]:
"""Why touch-predictions cannot read each item's `Touches:` list that it cannot. Every item is read, not only the next release's: a later item moves into the next release with its detail, and the list is fixed most cheaply where it was written.""" """One line per item whose `Touches:` list touch-predictions cannot read, saying why. Every item is read, not only the next release's: a later item moves into the next release with its detail, and the list is fixed most cheaply where it was written."""
details = item_details(todo) details = item_details(todo)
if isinstance(details, Failure): if isinstance(details, Failure):
return [details.reason] return [details.reason]
+2 -2
View File
@@ -12,7 +12,7 @@ then by ID. Then it moves each blocker, an item another's Blocked by cell names,
an item it blocks to just above the first such item. Orders the details to match. Writes each an item it blocks to just above the first such item. Orders the details to match. Writes each
item's R, and adds the Blocked by and R columns to a table without them. --check doesn't write item's R, and adds the Blocked by and R columns to a table without them. --check doesn't write
anything and fails when the file is not ranked as it would be, or when an item's detail holds a anything and fails when the file is not ranked as it would be, or when an item's detail holds a
`Touches:` list that touch-predictions cannot read, as `touch-predictions --help` spells it. `Touches:` list not spelt as `touch-predictions --help` shows.
A valid todo.md; ## Details and each item's detail are optional: A valid todo.md; ## Details and each item's detail are optional:
@@ -88,7 +88,7 @@ Exit 1, saying why, on bad arguments, a checkout no config names or a config tha
file given that is not the config's plan, a file that cannot be read or written, a todo.md, goals file or docs/decisions.md that breaks the file given that is not the config's plan, a file that cannot be read or written, a todo.md, goals file or docs/decisions.md that breaks the
rules above, a scoring run on docs/comprehension-history.md's newest scored commit with no Mean row rules above, a scoring run on docs/comprehension-history.md's newest scored commit with no Mean row
ending in its overall, an item that is not exempt scoring under the bar, or --check finding the file ending in its overall, an item that is not exempt scoring under the bar, or --check finding the file
unranked or a `Touches:` list it cannot read. unranked, or an item's `Touches:` list unreadable.
""" """
import pathlib import pathlib
import sys import sys
+1 -1
View File
@@ -30,4 +30,4 @@ paths:
- **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. - **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. - **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`. - **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, and 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`: `## Loop` (small)``. `todo-item add`, `todo-item edit` and `rank_todo.py --check` refuse a list touch-predictions cannot read. 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. - **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.