Answer prose round 1: a finding against a principle names it, a plainer changelog, and the contrastive-tail exception in prose.md
This commit is contained in:
+3
-3
@@ -2,10 +2,10 @@
|
||||
|
||||
## Unreleased
|
||||
|
||||
- A session no longer reads the technical principles before writing code. It writes the simplest change that solves its item, test first where the item changes code, and reads a principle only when the item changes it, a finding names it, or a decision or `todo.md` item it writes cites it. larv-review's reviewers hold the change to the principles, and each finding names the principle it applies. Expect more findings from the prose and stability reviewers, since sessions no longer load the rules for comments and READMEs.
|
||||
- Those rules, "Quality" and the examples behind "Prose" moved to `skills/larv-review/standards/`, which the prose and stability reviewers and `loop-claude`'s judge read. `CLAUDE.md` keeps a short core of "Prose"; sorting where order carries no meaning lives only in the technical principles.
|
||||
- A session no longer reads the technical principles before writing code. It writes the simplest change that solves its item, test first where the item changes code, and reads a principle only when the item changes it, a finding names it, or a decision or `todo.md` item it writes cites it. larv-review's reviewers hold the change to the principles, and a finding against one names it. Expect more findings from the prose and stability reviewers, since sessions no longer load the rules for comments and READMEs.
|
||||
- The rules for comments and READMEs, "Quality" and the examples behind "Prose" moved to `skills/larv-review/standards/`, which the prose and stability reviewers and `loop-claude`'s judge read. `CLAUDE.md` keeps a short core of "Prose"; sorting where order carries no meaning lives only in the technical principles.
|
||||
- A session no longer points out a preference you have repeated or asks you to write it up, and no longer restructures `CLAUDE.md` and `rules/` after changing them.
|
||||
- A `todo.md` item names a release whose bump semver allows.
|
||||
- A `todo.md` item names a release whose version bump fits the item under strict semver: a major for a change to what exists (a minor before 1.0.0), a minor for an addition, a patch for a fix.
|
||||
- `CLAUDE.md` keeps only the rules no file path can scope. The rules for `todo.md` items, decisions and a README's Goals and Audience moved to files under `rules/`. Claude Code loads each one when a session reads or writes a matching file. `loop-claude`'s judge reads them beside `CLAUDE.md`.
|
||||
- A README no longer holds cross-cutting decisions; `docs/decisions.md` does.
|
||||
- A technical principle, "Prefer deep modules": a module puts a small, intuitive interface in front of a lot of hidden work, and hides how it works but never what it depends on. It wins over "Explicit over implicit" unless hiding the work makes it harder for someone new to the project to tell what a call does. "Functional core, imperative shell" moves up to second place, a core rule beside "Compose, do not entangle" that no other principle overrides. The systems architect holds every module to it.
|
||||
|
||||
@@ -12,7 +12,7 @@ How work proceeds in any repo, unless the repo's `AGENTS.md` says otherwise. The
|
||||
- **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.
|
||||
- **Implement the simplest change that solves the item, and ship it with `/larv-review`.** When it changes code, write a failing test for it first. Its reviewers hold the change to the technical principles, each finding naming the principle it applies, and you fix what they find. Read a file under `~/.claude/principles/` only when the item changes it, a finding or a record you write names it, or you decline a finding.
|
||||
- **Implement the simplest change that solves the item, and ship it with `/larv-review`.** When the item changes code, write a failing test first. Its reviewers hold the change to the technical principles, and a finding against one names it. Read a file under `~/.claude/principles/` only when the item changes it, a finding or a record you write names it, or you decline a finding.
|
||||
- **Remove a finished item's row and detail from `todo.md`, and revise any decision that cites it.** If the repo publishes something others consume — a package, an image, an API — reword the item for them and move it to `CHANGELOG.md` under `## Unreleased`. A changelog is for the public, never for the next agent. Otherwise delete it; git history is the record.
|
||||
- **Releases are the human's.** The version bump and the publishing credentials are theirs, whatever another rule says. Prepare everything else, so cutting a release is one decision.
|
||||
- **Open each `todo.md` item or ticket with a bold one-sentence tagline**, so the taglines alone say what a release holds. The tagline states the target state, checkable when done: an imperative verb plus what holds afterwards. A present-tense fact reads as the current state and says nothing about what to do. Add "today X" only where the direction is otherwise ambiguous. GOOD: `**Accept undefined in MetadataValue and drop such keys on output.**` BANNED: `MetadataValue accepts undefined; such keys are dropped on output`.
|
||||
|
||||
@@ -3,7 +3,7 @@ import pathlib
|
||||
from loop_claude.project.text_file import read_utf8
|
||||
from loop_claude.stop import Stop
|
||||
|
||||
# The records: these project files and the human's rules; the judge reads them beside the README's premises.
|
||||
# The records the judge reads beside the README's premises: these project files, then the human's rules below.
|
||||
RECORD_FILES = ("AGENTS.md", "docs/decisions.md")
|
||||
# The human's rules for every project, under ~/.claude: CLAUDE.md, then each .md file in these folders.
|
||||
HUMAN_RULES_FILE = "CLAUDE.md"
|
||||
|
||||
+6
-2
@@ -155,8 +155,12 @@ Valid while Claude Code loads `~/.claude/rules/*.md` in every project, a path-sc
|
||||
|
||||
## worker: a chunk's worker writes the simplest change that solves its item, test first where it changes code, and reads a technical principle only where the item, a finding or its own record names it; larv-review's reviewers hold the change to the principles and to the standards in `skills/larv-review/standards/`
|
||||
|
||||
2026-10-13, lilleman through todo item 104, implemented by claude. Serves goals 1.4 and 1.5. Like red, green, refactor: the worker makes the item work, and the review passes raise it to the bar. A loop-claude worker loaded `CLAUDE.md` and every file under `rules/`, 4,247 words, and `CLAUDE.md` told it to read `technical-principles.md` too, 2,426 words more. The reviewers read the principles anyway, and each finding names the principle it applies.
|
||||
2026-10-13, lilleman through todo item 104, implemented by claude. Serves goals 1.4 and 1.5. Like red, green, refactor: the worker makes the item work, and the review passes raise it to the bar. A loop-claude worker loaded `CLAUDE.md` and every file under `rules/`, 4,247 words, and `CLAUDE.md` told it to read `technical-principles.md` too, 2,426 words more. The reviewers read the principles anyway, and a finding against one names it.
|
||||
|
||||
The worker keeps what it needs to write its own work. Each project's decision titles stay in its `AGENTS.md`, since a worker that misses a decision builds the wrong behaviour. A core of "Prose" stays in `CLAUDE.md`, since no reviewer reads the worker's chat. lilleman chose both on 2026-10-13. The rules for writing Goals and Audience, `todo.md` items and decisions stay in `rules/`, since writing those is the worker's job. `bin/rule-hook` stays: it blocks what a program can check, at no context cost. "Quality", the rules for comments and READMEs, and the examples behind "Prose" moved to `skills/larv-review/standards/`, which no path loads. The prose and stability reviewers read them, and so does loop-claude's judge. They sit beside larv-review, whose passes apply them; `principles/` stays where it is, since the principles auditor reads it per file. A finding names the principle it applies, so the worker reads only that one when it fixes or declines the finding. The worker still writes a failing test first for a change to code, since no reviewer can make a test come first. A chunk that changes no code, config or test, such as one that only plans, meets no principles review; the chunk that implements its items does. The prose reviewer checks a doc's order. The item also cut the rule that a session proposes new rules for `CLAUDE.md` and `rules/` and restructures them after each change: changes to these rules go through this repo's chunks and their reviews, like any other change.
|
||||
The worker keeps what it needs to write its own work. Each project's decision titles stay in its `AGENTS.md`, since a worker that misses a decision builds the wrong behaviour. A core of "Prose" stays in `CLAUDE.md`, since no reviewer reads the worker's chat. lilleman chose both on 2026-10-13. The rules for writing Goals and Audience, `todo.md` items and decisions stay in `rules/`, since writing those is the worker's job. `bin/rule-hook` stays: it blocks what a program can check, at no context cost. "Quality", the rules for comments and READMEs, and the examples behind "Prose" moved to `skills/larv-review/standards/`, which no path loads. The prose and stability reviewers read them, and so does loop-claude's judge. They sit beside larv-review, whose passes apply them; `principles/` stays where it is, since the principles auditor reads it per file.
|
||||
|
||||
A finding against a principle names it, so the worker reads only that one when it fixes or declines the finding. The worker still writes a failing test first for a change to code, since no reviewer can make a test come first. A chunk that changes no code, config or test, such as one that only plans, meets no principles review; the chunk that implements its items does. The prose reviewer checks that a doc sorts a list whose order carries no meaning.
|
||||
|
||||
The item also cut the rule that a session proposes new rules for `CLAUDE.md` and `rules/` and restructures them after each change: changes to these rules go through this repo's chunks and their reviews, like any other change.
|
||||
|
||||
Valid while review rounds per pass do not rise. A principle found late, such as functional core, can cost a rewrite within a pass's three rounds. `todo.md` item 105 compares rounds per pass and reading cost in loop-claude's archive for the five chunks before and after this one.
|
||||
|
||||
@@ -62,7 +62,7 @@
|
||||
- Defaults live at the program's edge: a CLI, a config file, a library's public API. A library still asks for every input that can change between runs, such as data, the clock and randomness; only the code that wires a program together, such as its CLI, defaults those, as "Functional core, imperative shell" asks.
|
||||
- BANNED: a CLI that refuses to run until given `--data-path` and `--seed`, when nearly every run wants the shipped data and fresh randomness. GOOD: it uses the shipped data and fresh randomness unless a flag overrides them, and `--help` names those flags.
|
||||
* Deterministic order wherever order carries no meaning.
|
||||
- Sort it, on a key that does not move: the name a line introduces, never where it came from. Exception: `id` goes first. A sorted list is searchable, its diff shows only what changed, and two edits to it conflict only where they mean to.
|
||||
- Sort such a list, on a key that does not move: the name a line introduces, never where it came from. Exception: `id` goes first. A sorted list is searchable, its diff shows only what changed, and two edits to it conflict only where they mean to.
|
||||
- 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.
|
||||
* Keep It Simple, Stupid (KISS): keep solutions simple, so a reader new to the project understands each part on one read.
|
||||
- Keep a size or complexity limit only while the comprehension panel's readers (`~/.claude/skills/comprehension-panel/`) find the code it flags hard.
|
||||
|
||||
@@ -7,4 +7,4 @@ How a reviewer applies each priority of `~/.claude/CLAUDE.md` → "Prose".
|
||||
3. **Default to delete.** Adding words is a deliberate act: name what a reader could not understand without them.
|
||||
|
||||
- **Write the thing, not an introduction to it.** A sentence announcing what follows, or flagging that it deserves attention, carries nothing — if it matters, it is in what follows. A bare label is fine. BANNED: `Here's the new audience text, which is the part that needs your eye:`, `One thing I changed that deserves your attention.`, `One judgment call I'd flag rather than bury.`, `Three things came along that would otherwise have been left false.` GOOD: `New audience text:`, or the list alone.
|
||||
- **No contrastive tail**, such as `X rather than Y`, `not Y but X` or `instead of Y`. BANNED: `verified in CI rather than asserted`. GOOD: `verified in CI`.
|
||||
- **No contrastive tail**, such as `X rather than Y`, `not Y but X` or `instead of Y`, unless naming the alternative stops a reader choosing it. BANNED: `verified in CI rather than asserted`. GOOD: `verified in CI`.
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
**A README covers what a reader needs *before* opening the code**: how it meets its goals, and how to build, test, run, and deploy it. It does **not** narrate an individual symbol, file, or test case — whoever wants to know what a test asserts opens the test, where the answer is exact and cannot drift.
|
||||
|
||||
**"Refresh `README.md` to match" means keep it true, not longer.** A change that alters a build/test/run/deploy step, a required env var, or a prerequisite makes the README a false claim by omission, fixed per `~/.claude/skills/larv-review/standards/quality.md` → "A false claim is a bug". Otherwise most changes need no README edit at all. GOOD: `run-tests.sh` gained a required `--profile` flag → update the documented command. BANNED: the change added a test case → add a paragraph describing it.
|
||||
**Refresh `README.md` only to keep it true.** A change that alters a build/test/run/deploy step, a required env var, or a prerequisite makes the README a false claim by omission, fixed per `~/.claude/skills/larv-review/standards/quality.md` → "A false claim is a bug". Otherwise most changes need no README edit at all. GOOD: `run-tests.sh` gained a required `--profile` flag → update the documented command. BANNED: the change added a test case → add a paragraph describing it.
|
||||
|
||||
## Package README (what someone finds on npm or GitHub)
|
||||
- The public API is the contract, so the README documents it: options, results, events, everything exported. The rule against narrating a file or test case still holds.
|
||||
|
||||
Reference in New Issue
Block a user