Merge pull request 'Read the plan and the decisions only as far as the chunk needs' (#257) from reading-cost-hot-files into main
This commit was merged in pull request #257.
This commit is contained in:
@@ -2,6 +2,7 @@
|
||||
|
||||
## Unreleased
|
||||
|
||||
- A session reads `todo.md` up to `## Details`, and the details of only the items its chunk takes. It reads a `docs/decisions.md` entry only where the entry's title leaves open what it needs. Both rules are in `CLAUDE.md`, so they hold from a session's start. The decisions rule replaces one in `rules/decisions.md`, which loads only once a session has opened `docs/decisions.md` or `AGENTS.md`. A chunk's opening line now counts the unreleased changes instead of listing them. Expect fewer tokens read before a chunk's first commit.
|
||||
- larv-review's stability and product-owner reviewers report only a defect, a requirement of the plan or the goals that the change breaks, a breach of a technical principle, or for stability a hard place the change touches; the stability reviewer leaves the style of comments to the prose reviewer, which now also reads help and error text. Each architect finding names a concrete later change the PR makes harder, and one that names none is dropped. The prose pass runs only on a chunk that changes prose a reader reads, such as docs, comments, help text or `todo.md`, and skips a code-only chunk. Expect fewer findings and fewer review rounds.
|
||||
- Every `todo.md` item carries a C score, how hard the change is to get right, from 1 to 10, in a column after S. C stays out of the score. `rank_todo.py` fails on an items table without the column, and the rule hook then blocks committing that `todo.md`. Before the next commit that changes a project's `todo.md`, add the column and score every item's C, as `rank_todo.py --help` shows.
|
||||
- The new `bin/score-outcomes` shows what finished chunks measured beside the R, S and C their items were guessed at: lines and files changed, review rounds, and 🔴 and 🟡 findings. It reads them from the default branch's merge commits, so a project that merges by squash or fast-forward shows none. Given a guess, it lists the 5 finished items guessed nearest. It always reports, for each score, the median outcome at each guessed value, once 10 chunks that each shipped one item record it: R against 🔴 findings, S against lines changed, C against review rounds past each pass's first. A session filing or editing an item runs it and scores R, S and C from what it shows.
|
||||
|
||||
@@ -8,8 +8,9 @@ How work proceeds in any repo, unless the repo's `AGENTS.md` says otherwise. The
|
||||
- **Plan `todo.md` as one scored table**: every item names the release that ships it. If `todo.md` has another shape, reshaping it is the chunk, and the human approves it.
|
||||
- **When the next release has no items and no work has landed towards it, plan it as this chunk.** Move the highest-scoring items of later releases into it, and get the human's approval of that set before writing any code.
|
||||
- **When the next release has no items left and work has landed towards it, it is finished: stop.** Report what it holds and that it is ready to cut. Under `/loop`, this ends the loop. Until the human cuts it, only a security fix lands, into that release; never start a later release's items or plan a new one.
|
||||
- **Open every chunk with one line:** the last version cut, what is unreleased (`CHANGELOG.md` → `## Unreleased`, or else the log since the last tag), and the release this chunk ships into. A repo that publishes nothing says so once.
|
||||
- **Open every chunk with one line:** the last version cut, how many changes are unreleased (the entries under `CHANGELOG.md` → `## Unreleased`, or else the commits since the last tag), and the release this chunk ships into. A repo that publishes nothing says so once.
|
||||
- **Read the README's `## Goals` and `## Audience` before starting a chunk, unless your prompt quotes them.** The chunk's items set its scope. The goals choose between ways to deliver those items, and never add to them.
|
||||
- **Read the plan and the decisions only as far as the chunk needs.** Run `grep -n '^## Details' todo.md`, then read `todo.md` with the Read tool up to the line it prints, or whole when it prints none. Then read the details of only the items the chunk takes. `AGENTS.md` lists every decision's title. Read the entry under a title in `docs/decisions.md` only where the title leaves open what the chunk or the review needs.
|
||||
- **Work one chunk at a time, and make it as large as one purpose allows.** Every review has a fixed cost, so a chunk takes the next plan item plus every other item for which three things hold: one PR title states what they achieve together, without listing them; they name one release; and they fire the same review passes (`larv-review` §3). Tiny items, a few lines of change each, need neither a shared purpose nor the same passes: bundle up to ten that name one release into one chunk. Split a milestone into items in `todo.md` before starting it. Fix a finding in the chunk's own change within the chunk. File a finding about anything else in `todo.md`. An item marked `question` waits for the human; take the next item.
|
||||
- **Ask, don't guess.** First check whether the goals already answer the question. If they nearly do, propose a change to the goals and show how it answers this case: an answer settles one question, a goal settles every question like it. Write every answer once, where it belongs, never only in chat: a goal in `README.md`, a working rule in `AGENTS.md`, a standing choice in a comment at the one place it governs, or in `docs/decisions.md` once made in more than one place. When an answer holds a goal and a choice, write the goal in the README, and record as a choice only what the goal leaves open.
|
||||
- **Bench a syntax with the people who write it.** Before a new or changed spelling of something users read or write ships — markdown, HTML, a config key, a CLI flag — a panel of fresh-context readers, seated as those users from the README's `## Audience`, picks it.
|
||||
@@ -38,7 +39,7 @@ Reviewers hold prose to the full rules, with examples: `~/.claude/skills/larv-re
|
||||
|
||||
## Topic rules
|
||||
|
||||
Claude Code loads a rule file when a session reads or writes a file its `paths:` frontmatter matches, and after a write only once the write is done. Read a rule file before you create a file it covers.
|
||||
Claude Code loads a rule file when a session writes a file its `paths:` frontmatter matches, or reads one with the Read tool or `head -n`, never `sed`. After a write, it loads only once the write is done. Read a rule file before you create a file it covers.
|
||||
|
||||
- The decision log: `~/.claude/rules/decisions.md`.
|
||||
- README goals and audience: `~/.claude/rules/goals-and-audience.md`.
|
||||
|
||||
@@ -1560,3 +1560,56 @@ Inherited architect, decided by:
|
||||
- Locality, Overall: `skills/larv-review/SKILL.md:101` "Comprehension check": runs once, blocks nothing, no pass; at 4cc9953 "Fresh" made a prose fix in §3 change what §5 must do
|
||||
- Locality: `bin/comprehension_history.py:126` `worse_votes`: recovers votes by re-parsing table rows by cell count, relying on the votes table coming first, which matters only for legacy rulings
|
||||
- Locality: `bin/rule_hook/git.py:11` `git`: same name as `bin/git_repo.py:8` `git` with a different contract, beside two more git-named units
|
||||
|
||||
## 2026-10-13T15:24:20Z, PR #257 at d471377
|
||||
|
||||
| Seat | Navigation | Locality | Shape | Self-sufficiency | Overall |
|
||||
|---|---|---|---|---|---|
|
||||
| Junior A | 7 | 6 | 6 | 6 | 6 |
|
||||
| Mid A | 7 | 7 | 6.5 | 6.5 | 6.5 |
|
||||
| Maintainability senior | 7 | 6.5 | 6.5 | 7.5 | 7 |
|
||||
| Inherited architect | 7 | 7 | 6 | 6.5 | 6.5 |
|
||||
| Mean | 7.00 | 6.63 | 6.25 | 6.63 | 6.50 |
|
||||
|
||||
Junior A, hardest first:
|
||||
|
||||
- `skills/larv-review/SKILL.md:63` "Round cap" and `:74` "Re-entry": seven interlocking rules on reruns, caps and exceptions, each pointing elsewhere; what a fix to a stability 🟡 that touches a comment reruns stayed unclear
|
||||
- `bin/comprehension_history.py:106` `latest_places`: a 70-word docstring, an index rule resting on a pre-PR #255 history quirk, and `worse_votes` keeping the first row by `setdefault`
|
||||
- `bin/loop_claude/cycle/judge.py:16` `JUDGE_RULES` and `:127` `run_judge`: behaviour in a prose prompt, and three text normalisations held at once
|
||||
- `bin/rule_hook/override_log.py:36` `this_chunks`: reflog and branch-name rules that need git knowledge
|
||||
- `bin/shell_command.py:31` `segments`: dense regexes and a second lexing path for unbalanced quotes
|
||||
- `bin/loop_claude/cycle/states.py:69` `transition`: the quoted-answers counter threads through three states
|
||||
- `bin/larv_review/plan.py:9` `scoring_run_due`: "landed", "next release" and "emptied" mix two plans
|
||||
- `bin/transcript_archive/write.py:13` `archive`: three invariants on folder naming and write order
|
||||
|
||||
Mid A, hardest first:
|
||||
|
||||
- `skills/larv-review/SKILL.md:63` "Round cap": about 30 interlocking rules across the trigger table, the fix clauses, the cap and later rounds; only the count is enforced in code
|
||||
- `bin/comprehension_history.py:106` `latest_places`: parses its own markdown by label regexes, resting on table order and a legacy case
|
||||
- `bin/loop_claude/cycle/judge.py:16` `JUDGE_RULES`: the prompt is assembled from constants in three modules
|
||||
- `bin/rule_hook/override_log.py:36` `this_chunks`: reflog semantics trusted, not verifiable by reading
|
||||
- `bin/shell_command.py:31` `segments`: a hand-rolled tokenizer two unrelated tools depend on
|
||||
- `bin/larv_review/ruling.py:8` `votes`: the vote-counting rule spread over four modules and an 80-line help, with a ruling decision inside a parser
|
||||
- `bin/rank_todo.py:378` `rank_details`: regex split and string splicing whose newline round-trip needs running to trust
|
||||
- `bin/transcript_archive/write.py:13` `archive`: the why lives in `loop_claude/loop/main.py`'s docstring
|
||||
|
||||
Maintainability senior, hardest first:
|
||||
|
||||
- `skills/larv-review/SKILL.md:63` "Round cap" and `:74` "Re-entry": a state machine written as prose, re-derived on each read
|
||||
- `bin/comprehension_history.py:106` `latest_places`: dense comprehensions, a seat name recovered by splitting a label, and table-order dependence
|
||||
- `bin/loop_claude/cycle/judge.py:16` `JUDGE_RULES` and `:127` `run_judge`: one prompt spliced from three files, and two misquotes treated differently
|
||||
- `bin/rule_hook/override_log.py:36` `this_chunks`: four branches over reflog behaviour
|
||||
- `bin/reading_cost/measure.py:27` `measure`: timestamps compared as strings with the format assumption unstated
|
||||
- `bin/rule_hook/rules.py:49` `OVERRIDE`: a lazy reason with a lookahead and a suffix strip, explained nowhere in the code
|
||||
- `bin/larv_review/plan.py:9` `scoring_run_due`: the "work has landed" rule, written three times
|
||||
- `bin/loop_claude/loop/reload.py:50` `exec_if_edited`: editing any `bin/**/*.py` re-execs a running loop
|
||||
|
||||
Inherited architect, would restructure first:
|
||||
|
||||
- `bin/round_titles.py:5` `PASSES`: repeats the pass table at `skills/larv-review/SKILL.md:33` with no check tying them, and omits the auto-reviewer
|
||||
- `skills/larv-review/SKILL.md:71` "Cap": the round cap is prose; no code stops a fourth round, so the 3am path takes 20 to 40 minutes
|
||||
- `bin/git_repo.py:8` `git`: one of five git runners with four signatures
|
||||
- `bin/larv_review/git.py:6` `history_changes`: a module named git that holds history logic
|
||||
- `bin/reading_cost/measure.py:16` `Reading`: "places" also names comprehension places, and "record" and "outcome" each carry three meanings
|
||||
- `bin/loop_claude/cycle/judge.py:16` `JUDGE_RULES`: says "the agent" where the code says "worker", and restates the working loop unchecked
|
||||
- `bin/loop_claude/loop/reload.py:38` `fingerprint`: covers every `bin/**/*.py`, so editing `statusline.py` reloads the loop
|
||||
|
||||
@@ -229,3 +229,22 @@ Read most (opens and searches):
|
||||
- `bin/comprehension_history.py` 2
|
||||
- `bin/larv_review/record.py` 2
|
||||
- `bin/larv_review/ruling.py` 2
|
||||
|
||||
## Reading cost, chunk 3c24e750f1ba, finished 2026-10-13T15:05:38Z
|
||||
|
||||
70488 new input tokens before the first commit.
|
||||
|
||||
Read most (opens and searches):
|
||||
|
||||
- `todo.md` 5
|
||||
- `README.md` 4
|
||||
- `docs/decisions.md` 4
|
||||
- `agents/systems-architect.md` 3
|
||||
- `agents/stability-reviewer.md` 2
|
||||
- `skills/larv-review/SKILL.md` 2
|
||||
- `AGENTS.md` 1
|
||||
- `CHANGELOG.md` 1
|
||||
- `CLAUDE.md` 1
|
||||
- `agents/principles-auditor.md` 1
|
||||
|
||||
## Reading cost reset, 2026-10-13T15:08:08Z
|
||||
|
||||
+1
-1
@@ -6,6 +6,6 @@ paths:
|
||||
|
||||
# Decisions: one home, each linked to a goal or a technical principle
|
||||
|
||||
**The decision log has one home: `docs/decisions.md`**. A title states the whole decision in one line: what holds at the commit it ships in, in words a reader finds in the code or the plan. `AGENTS.md` lists every title, so a session works by the decisions without loading their background. A session reads the entry under a title only to question, revise or add a decision. The entry holds the background: its date, who made it, the reasoning, and the premise it rests on ("valid while X") so it can expire honestly when that premise dies.
|
||||
**The decision log has one home: `docs/decisions.md`**. A title states the whole decision in one line: what holds at the commit it ships in, in words a reader finds in the code or the plan. `AGENTS.md` lists every title, so a session works by the decisions without loading their background. The entry holds the background: its date, who made it, the reasoning, and the premise it rests on ("valid while X") so it can expire honestly when that premise dies.
|
||||
|
||||
**Every decision links to a goal or a technical principle.** An entry names the goal it serves or the technical principle under `~/.claude/principles/` it applies; one that can do neither is a missing goal, and an entry already in the repo with neither behind it is a finding. Propose the goal, never a reason of your own — `~/.claude/CLAUDE.md` → "Working loop", "Ask, don't guess" says how. An entry working against a goal or a technical principle stands only while it names the `todo.md` item that ends it.
|
||||
|
||||
@@ -24,7 +24,6 @@
|
||||
|
||||
| ID | Release | Exempt | Item | R | S | C | A | G | Goals | Score |
|
||||
|---|---|---|---|---|---|---|---|---|---|---|
|
||||
| 109 | 0.1.0 | | **Lower the reading cost of the files a chunk reads most before its first commit.** | 2 | 4 | 4 | 5 | 6 | 1.4 | 18.5 |
|
||||
| 93 | 0.2.0 | | **Let a chunk's worker start below the project's model, once the archive shows chunks on a lower rung took no more review rounds than chunks on the project's model.** | 3 | 2 | 6 | 6 | 7 | 1.1, 1.4 | 22.4 |
|
||||
| 94 | 0.2.0 | | **Every 20th cycle, have loop-claude measure token spend and routing outcomes, file them here, and interrupt the human only when they call for a routing change.** | 3 | 5 | 6 | 6 | 7 | 1.1, 1.4 | 21.6 |
|
||||
| 88 | 0.2.0 | | **Define one routing ladder of (model, effort) rungs ordered by a published ranking of their competence, and map a task's R + C to a rung relative to the project's model.** | 3 | 4 | 5 | 6 | 7 | 1.4 | 21.4 |
|
||||
@@ -46,7 +45,7 @@
|
||||
| 59 | 0.3.0 | | **Bound a run of unfinished verdicts on one chunk, so a worker and judge that disagree cannot cycle unattended without end.** | 3 | 3 | 5 | 6 | 6 | 1.4 | 19.8 |
|
||||
| 12 | 0.3.0 | | **Run the test suite in CI on every PR, or record in `docs/decisions.md` why the local run is enough.** | 2 | 4 | 3 | 4 | 6 | 1.1 | 16.9 |
|
||||
| 80 | 0.3.0 | | **State in README → Install that every machine taking this checkout must be a sandbox, as `settings.json`'s auto mode assumes.** | 1 | 1 | 1 | 5 | 5 | 4 | 16.8 |
|
||||
| 62 | 0.3.0 | | **Lift Locality, Self-sufficiency and the overall to the comprehension floor, at the places the seats name.** | 4 | 6 | 6 | 5 | 6 | 1.1 | 16.4 |
|
||||
| 62 | 0.3.0 | | **Lift Locality, Shape, Self-sufficiency and the overall to the comprehension floor, at the places the seats name.** | 4 | 6 | 6 | 5 | 6 | 1.1 | 16.4 |
|
||||
| 5 | 0.3.0 | decision | **Key a project on its checkout's full path, and refuse to start while another session uses that key.** | 5 | 5 | 7 | 5 | 6 | 1.1 | 15.6 |
|
||||
| 84 | 0.3.0 | | **Check, at each release's scoring run, that seats in a paired ruling agree more often than two scoring runs on near-identical code do, as the paired-ruling decision assumes.** | 2 | 2 | 5 | 4 | 5 | 1.4 | 15.1 |
|
||||
| 67 | 0.3.0 | principle | **Point stability-reviewer at the technical principles in place of its own restatement of them.** | 2 | 3 | 2 | 4 | 5 | 1.3 | 14.9 |
|
||||
@@ -72,10 +71,6 @@
|
||||
|
||||
## Details
|
||||
|
||||
### 109. Lower the reading cost of the files a chunk reads most before its first commit.
|
||||
|
||||
`bin/reading-cost` found a rise: the last 5 chunks' median is 136132 new input tokens before their first commit, the 5 before them 56802. Files read most in those 5 chunks (opens and searches): `todo.md` 31, `docs/decisions.md` 20, `CHANGELOG.md` 11, `README.md` 11, `bin/larv_review/test_larv_review.py` 10, `skills/larv-review/SKILL.md` 9, `CLAUDE.md` 7, `agents/stability-reviewer.md` 5, `bin/loop_claude/loop/main.py` 5, `bin/test_rank_todo.py` 5. The chunk that ships this item runs `reading-cost --reset`.
|
||||
|
||||
### 93. Let a chunk's worker start below the project's model, once the archive shows chunks on a lower rung took no more review rounds than chunks on the project's model.
|
||||
|
||||
Goal 1.1 asks for proven quality, so stepping down waits on the archive's evidence.
|
||||
@@ -180,12 +175,14 @@ When CI runs a rule check, such as one of `bin/rule-hook`'s, let `<!-- rule-over
|
||||
|
||||
Raised by the principles audit of PR #224. The `settings.json` decision is valid while every machine taking this checkout is a sandbox, but Install asks for a sandbox only for `loop-claude`, so a new machine is never told.
|
||||
|
||||
### 62. Lift Locality, Self-sufficiency and the overall to the comprehension floor, at the places the seats name.
|
||||
### 62. Lift Locality, Shape, Self-sufficiency and the overall to the comprehension floor, at the places the seats name.
|
||||
|
||||
Raised by the principles audit of PR #215 against KISS, in `principles/technical-principles.md`, and goal 1.1.
|
||||
|
||||
PR #234's last scoring run, at b2a277b, put Locality and Self-sufficiency at 6.50 and the overall at 6.75. Every seat named larv-review's rules, which cannot be followed without `skills/larv-review/SKILL.md` §3 open beside the code: the pass list lives in both `bin/round_titles.py` `PASSES` and the skill's table, which also counts the auto-reviewer; `bin/comprehension_history.py` is reader, writer and seat registry in one, and parses the history by regex for two tools. Also named: the judge's prompt assembled from `cycle/judge.py`, `cycle/prompts.py` and `project/records.py`; git run four ways, in `bin/larv_review/git.py`, `bin/metric_bench/main.py`, `bin/reading_cost/main.py` and `bin/loop_claude/effects.py`; `SeatsFile.read`, a field named like a method.
|
||||
|
||||
PR #257's scoring run, at release 0.1.0's end, put Locality and Self-sufficiency at 6.63, Shape at 6.25 and the overall at 6.50. Shape fell under the floor on the flat `bin/` root of about 30 entries, the five git runners, and "record", "outcome" and "places" each naming several things. The seats again named the places above.
|
||||
|
||||
### 5. Key a project on its checkout's full path, and refuse to start while another session uses that key.
|
||||
|
||||
The key names the project's session, archive folder and models entry. `project_key` drops the leading `/`, so `~/code/a` and `/a` share all three, and one loop can resume or delete the other's session.
|
||||
|
||||
Reference in New Issue
Block a user