Answer prose round 1: 0 🔴, 4 🟡; point the architect's probes at the principle, ask for a grouping or a reason in place of 'never a verdict', and say what a level costs

This commit is contained in:
2026-10-22 19:24:14 +02:00
parent 5805bd2287
commit 057808ad25
6 changed files with 11 additions and 11 deletions
+1 -1
View File
@@ -49,7 +49,7 @@ Decisions live in `docs/decisions.md`:
- routing: a worker whose run ends asking for a higher rung, citing an escalation trigger the judge finds in the transcript, steps one rung up as the judge interrupts or quotes an answer, or next cycle, up to two rungs above the rung its item picks
- routing: on a model judge-replay covered, the judge runs on the rung a review would get from the highest E + I among its chunk's items, never below the project's rung
- routing: a review pass runs below the project's rung only on a rung that a replay of its rounds shows finding every 🔴 and 🟡 the project's rung finds, and only where the E + I steps no review up and the worker runs no higher than the project's rung, then even below the worker's; no pass has such a rung
- principles: about seven things per level, four or five where they act on each other, more where a reader finds them by name; crossing a limit is a prompt, never a verdict
- principles: about seven things per level, four or five where they act on each other, more where a reader finds them by name; crossing a limit asks for a grouping or a recorded reason
## Working rules
+1 -1
View File
@@ -2,7 +2,7 @@
## Unreleased
- A new technical principle, "About seven things per level", sets soft limits on what a reader takes in at once: the parameters and branches of a function, the methods of a class, the files and folders in a folder, the sections of a document and the components of a system. Things that act on each other aim for four or five, and things found by name, such as files named by locale, may run far past seven. Crossing a limit asks you to group the things or record why they stay. The systems-architect reviewer now reads its limits from this principle. It rates a unit past one with no recorded reason a 🟡, where it used to be a 🔴, and no longer asks for the limits as merge-gate rules.
- A new technical principle, "About seven things per level", sets soft limits on what a reader takes in at once: the parameters and branches of a function, the methods of a class, the files and folders in a folder, the sections of a document and the components of a system. Aim for four or five of the things that act on each other, such as parameters. Things found by name, such as files named by locale, may run far past seven. Crossing a limit asks you to group the things or record why they stay. The systems-architect reviewer now reads its limits from this principle. It rates a unit that crosses a limit with no recorded reason a 🟡, where it used to be a 🔴, and no longer asks for the limits as merge-gate rules.
- The comprehension panel's base worktree and a build probe's output now go in a folder under the chunk's review folder in `~/.local/state/larv-review/`. Both used to go in a session scratchpad, which loop-claude's headless sessions don't have.
- rule-hook now reads `git > out commit -m x` as one git commit, as the shell runs it. A redirect used to split a command in two, so such a commit escaped `commit-one-line`, `round-title-counts` and `todo-rank-check`.
+3 -3
View File
@@ -40,7 +40,7 @@ Short-term pragmatism on these points compounds into long-term decay. Push back
## Fits in a head
At every altitude — system, component, class, method — the thing in view must be graspable with the details below abstracted away. This is the fractal test: zoom in anywhere and what you see still fits. A design only comprehensible by holding two levels at once has failed it, however clean each level looks in isolation. A new developer explains what the system does from its structure in under 30 minutes.
At every altitude — system, component, class, method — the thing in view must be graspable with the details below abstracted away. This is the fractal test: zoom in anywhere and what you see still fits. A design only comprehensible by holding two levels at once has failed it, however clean each level looks in isolation. A new developer should explain what the system does from its structure in under 30 minutes; where they cannot, find the level that fails.
The limits per level are the technical principle "About seven things per level" in `~/.claude/principles/technical-principles.md`. A unit over one is first a prompt to check responsibilities: if it holds several, split along the concept boundaries. If it holds one, decompose it into named steps a reader can follow one at a time, or let it stay whole for a reason the principle accepts. "Single responsibility" answers the count of responsibilities, never the count of things a reader must hold in their head. A unit past a limit with no recorded reason is a 🟡. It is a 🔴 only where you name what a reader cannot hold: the failed fractal test is the defect, never the count. A core method nobody can hold in their head is a structural finding, never style.
@@ -163,7 +163,7 @@ Focus on architectural alignment:
- Does it add complexity that could be avoided — including by relaxing the requirement that forces it? If a simpler design gets almost the same result, name it and the behavior delta rather than accepting the complex shape as given.
- Does it duplicate a concept that already exists instead of reusing it? (see "One concept, one implementation".)
- Does it build generality for a scale or future the Stage 0 record doesn't name? Same weight as unreasoned duplication (see "Hunt the imagined requirement").
- Does it push a core unit past a limit that Fits in a head names?
- Does it push a core unit past a limit of "About seven things per level" in `~/.claude/principles/technical-principles.md`?
- Does it match the patterns documented in the README?
- Take the language and framework as given — only reopen foundational choices when the work itself does (see Evaluating Foundational Choices).
@@ -177,7 +177,7 @@ This is where unjustified duplication and accidental complexity get caught. Run
1. **Inventory the core concepts.** List the handful of ideas the system is really built on (e.g. "the navigation menu", "a list+filter+paginate page", "a form", "the request context"). For each, find *every* place it is implemented.
2. **One concept, one implementation — or a stated reason.** If a concept is implemented more than once, each copy must point to a concrete reason it cannot be the shared one. No reason → collapse to one. Slight, undesigned variation between copies is the signature of copy-paste drift, not deliberate design.
3. **Trace to the bottom — and walk the long chains.** Follow the central data structures and abstractions down to their foundation. Can you hold the core in your head? Is anything obscure, implicit, or magical on the way down? A core you cannot explain to the bottom is the defect, even when every layer looks tidy. Then pick the system's key operations and follow each call chain end-to-end (entry point → … → persistence/response). Every hop must add a decision, a transformation, or a boundary that earns its keep; a pass-through layer that only forwards is change amplification plus cognitive load with no payoff — name the collapse concretely (which layer folds into which). A chain, like a unit, must fit in a head (the hops limit that Fits in a head names).
3. **Trace to the bottom — and walk the long chains.** Follow the central data structures and abstractions down to their foundation. Can you hold the core in your head? Is anything obscure, implicit, or magical on the way down? A core you cannot explain to the bottom is the defect, even when every layer looks tidy. Then pick the system's key operations and follow each call chain end-to-end (entry point → … → persistence/response). Every hop must add a decision, a transformation, or a boundary that earns its keep; a pass-through layer that only forwards is change amplification plus cognitive load with no payoff — name the collapse concretely (which layer folds into which). A chain, like a unit, must fit in a head (the limit on hops in "About seven things per level" in `~/.claude/principles/technical-principles.md`).
4. **Naming and placement.** If a name, or its location in the tree, does not tell a new reader what it is and where it belongs, that is a defect — not a note. Names come from the domain glossary; the hierarchy should mirror the architecture with no translation. When a subsystem has been consolidated into its own folder/namespace, confirm *every* member lives there: a collaborator stranded in the parent (typically one the refactor didn't scope in, so it predates the move) breaks the mirror as badly as a misnamed file — a finding even when nothing imports it wrongly. Check both directions: the sibling in the parent that should have moved in, and the file inside the subfolder that actually belongs to a different layer. Ask of each remaining sibling in the parent: why is this *here* and not *there* with its peers? "It predated the move" is not a reason. Enumerate what's left in the parent namespace and justify each one, rather than only inspecting the files that changed.
5. **A flat directory is a smell at scale.** Count the files in each source directory. One folder holding many modules with no sub-structure (rule of thumb: **more than ~15–20 source files**, or a directory a newcomer can't skim to locate a concern) hides the architecture instead of mirroring it — the larger it grows, the more it costs to navigate, and "we'll group it later" never comes. This is a structural defect, not cosmetic polish: flag it and **propose a concrete grouping by concern**, naming which files go into which folder (e.g. `http/`, `auth/`, `admin/`, `plugin-host/`, `ui/`), derived from the core concepts the inventory already surfaced; co-locate tests with their module. Push for the reorganization rather than merely noting the count. The only thing that excuses a large flat tree is the project documenting it as a deliberate, reasoned deviation (and even then, re-test the reason as the file count climbs).
6. **Price the reasoned complexity too.** Essential-looking complexity has a requirement behind it. For each hotspot that survives the steps above, name that requirement, then sketch the design without it. When a much simpler near-equivalent exists, report the trade as a finding: the simpler shape, the exact functionality delta, and the complexity saved. A requirement nobody has priced is not a decision — offer the trade once, plainly, and let the owner accept or reject it.
+2 -2
View File
@@ -374,7 +374,7 @@ The prose pass went first: a missed prose finding breaks no behaviour, and a lat
Valid until a new model joins the ladder, which calls for a replay of every pass, or a pass's reviewer prompt changes, which calls for a replay of that pass.
## principles: about seven things per level, four or five where they act on each other, more where a reader finds them by name; crossing a limit is a prompt, never a verdict
## principles: about seven things per level, four or five where they act on each other, more where a reader finds them by name; crossing a limit asks for a grouping or a recorded reason
2026-10-22, lilleman asked for a rule of seven that holds at every level and is never a hard rule. Serves code health: a reader new to the project should take in each level at once. The numbers follow the sources below, since no single study sets them.
@@ -382,6 +382,6 @@ Valid until a new model joins the ladder, which calls for a replay of every pass
- Four or five for things that act on each other: working memory holds about four chunks once rehearsal and grouping are blocked (Cowan, ["The magical number 4 in short-term memory"](https://www.cambridge.org/core/journals/behavioral-and-brain-sciences/article/magical-number-4-in-shortterm-memory-a-reconsideration-of-mental-storage-capacity/44023F1147D4A1D44BDC0AD226838496), 2001). Sandi Metz's rules allow four parameters, and Fowler's long-parameter-list smell starts at three or four.
- More for things found by name: a reader recognises an item in a list, so a list's length is no memory limit (Nielsen Norman Group, [Short-term memory and web usability](https://www.nngroup.com/articles/short-term-memory-and-web-usability/)). Menu studies find depth costs more than breadth, and broad levels of 16 to 64 items beat narrow ones when their labels are clear (Larson & Czerwinski, [1998](https://www.microsoft.com/en-us/research/publication/web-page-design-implications-memory-structure-scent-information-retrieval/); Dix et al., [menu breadth](https://hcibook.com/e3/online/menu-breadth)).
- A split must save more than it costs: in an eye-tracking study, extracting methods cut reading time on hard tasks and raised it on simple ones (a 2026 preprint with 32 novices, [arXiv 2602.18579](https://arxiv.org/abs/2602.18579)). John Ousterhout's deep modules and John Carmack's case for inlined code argue the same against splitting by size.
- A prompt, never a verdict: no study supports a fixed cut-off for function length, parameter count or nesting. Re-analysis of the cited data finds no optimal function length ([Derek Jones, 2023](https://shape-of-code.com/2023/09/10/optimal-function-length-an-analysis-of-the-cited-data/)), and SonarSource set its Cognitive Complexity default by tuning out noise. So a limit holds only while the comprehension panel's readers find the code it flags hard. The systems-architect agent rates a unit past a limit with no recorded reason a 🟡, and a 🔴 only where it names what a reader cannot hold.
- A grouping or a recorded reason, never a split at any cost: no study supports a fixed cut-off for function length, parameter count or nesting. Re-analysis of the cited data finds no optimal function length ([Derek Jones, 2023](https://shape-of-code.com/2023/09/10/optimal-function-length-an-analysis-of-the-cited-data/)),. So a limit holds only while the comprehension panel's readers find the code it flags hard, and `agents/systems-architect.md` → "Fits in a head" says how its reviewer rates a unit past one.
Valid while the comprehension panel measures how hard a project is to read.
+3 -3
View File
@@ -75,11 +75,11 @@
- An import sorts on its first binding, not its path, so moving or renaming a module reorders nothing. Where lines already group by kind — type imports, host packages — the key sorts within each group.
* About seven things per level, so a reader new to the project can take in each level at once.
- A level is what a reader looks at together: the parameters of a function and its branches (cyclomatic complexity), the methods of a class, the files in a folder and the folders beside them, the sections of a document, the components of a system, the hops of a call chain. Past about seven, group the things under names a reader can follow; each group then counts as one.
- Things that act on each other must be held in mind together, and a mind holds about four. Aim for four or five of them and treat seven as the ceiling: parameters, branches and the values a function tracks. A function also fits on one screen, about 24 lines of 80 characters.
- Parameters, branches and the values a function tracks act on each other, so a reader holds them in mind together, and a mind holds about four. Aim for four or five of them, and treat seven as the ceiling. Keep a function to one screen, about 24 lines of 80 characters.
- Things a reader finds by name may run far past seven: 100 files named by locale, the cases of an enum, a reference list. A predictable name and a sorted order serve them better than a group would.
- Every level costs a jump, so a split must save more than it costs. Keep eight, nine or ten things in one level when splitting them would add more names, files or jumps than it removes. Say why where the level is declared: a comment, the folder's README.
- Each added level makes a reader open one more folder, file or function to find a thing, so a split must save more than it costs. Keep eight, nine or ten things in one level when splitting them would add more names, files or jumps than it removes. Say why where the level is declared: a comment, the folder's README.
- Group by what a reader would name: a feature, a step, what changes together. BANNED: `misc/`, `part2()` or a parameter object that exists only to bring a count down. GOOD: `invoices/`, `payments/`, `reports/`, each holding what changes together; `locales/` holding `de.json` to `zh.json`, flat.
- Crossing a limit is a prompt, never a verdict: group the things, or record why they stay. Keep a limit only while the comprehension panel's readers (`~/.claude/skills/comprehension-panel/`) find the code it flags hard.
- Crossing a limit asks for one of two answers, never a split at any cost: group the things, or record why they stay. Keep a limit only while the comprehension panel's readers (`~/.claude/skills/comprehension-panel/`) find the code it flags hard.
* Keep It Simple, Stupid (KISS): keep solutions simple, so a reader new to the project understands each part on one read.
* Don't Repeat Yourself (DRY) is a guide, not an absolute rule. It aims at one authoritative home per piece of knowledge, one obvious way per need. Before applying it, ask whether the code would be easier to understand, easier to reason about, or easier to maintain if DRY were broken; if so, break it, so long as the spellings cannot disagree (below). A surface people write — a template, data, an API — may accept a second spelling where that makes it easier to use.
- A value, rule, definition or concept lives in one place, and everywhere else derives it from there or points at it. A copy that can drift is a second spelling: derive it from its owner, or, for config a human writes, reject it where it is read and name the owner.
+1 -1
View File
@@ -338,7 +338,7 @@ The key names the project's session, archive folder and models entry. `project_k
### 155. Lower the reading cost of the files a chunk reads most before its first commit.
`bin/reading-cost` on 2026-10-22: the median of the last 5 chunks is 73,910 new input tokens before their first commit, up from 63,554 for the 5 before them. It listed no file read most over the last 5. The chunk that ships this item runs `bin/reading-cost --reset`.
`bin/reading-cost` on 2026-10-22: the median of the last 5 chunks is 73,910 new input tokens before their first commit, up from 63,554 for the 5 before them. Its list of the files read most over the last 5 was empty, so the chunk that takes this item first finds which files those chunks read. The chunk that ships this item runs `bin/reading-cost --reset`.
### 51. Hand loop-claude's terminal output to an injected effect, so no storage or retry function prints.