Ban a verb with nothing as its object in the prose rules, and fix the breaches in CLAUDE.md and two agents
CI / tests (pull_request) Successful in 2m4s
CI / tests (pull_request) Successful in 2m4s
This commit is contained in:
@@ -8,7 +8,7 @@ How work proceeds in any repo, unless the repo's `AGENTS.md` says otherwise. The
|
||||
- **Plan `todo.md` as one scored table, in the shape whose example `~/.claude/bin/rank_todo.py --help` shows**: every item names the release that ships it. Until `todo.md` has that shape, reshaping it is the only work, 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, its release review is the chunk** (`larv-review` §3 → "Release review"). **Once that has merged and the release holds no item, the release 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, or an item its release review filed, 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, 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.
|
||||
- **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 doesn't publish anything 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.** Where your prompt quotes `chunk-preflight`'s facts, they hold the next item's L, E + I, tagline and detail, and each item that may join it with its L, E + I, S, tagline and detail; open `todo.md` only for what they leave out. Otherwise 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 put every item that can share its review into it.** Every review has a fixed cost, so a chunk takes the next plan item plus every other item for which three things hold: they name one release; they fire the same review passes (`larv-review` §3); and no item outside the chunk blocks one of them. The items need not share a purpose. An item whose risk R, in `todo.md`, is above 5 ships alone: it joins no chunk, and none joins it. The next plan item is the first that does not wait: an item waits while it is marked `question`, until the human answers, or while an item that blocks it is still in the plan. Tiny items, a few lines of change each, need not fire the same passes: bundle up to ten that name one release, and that no item outside the chunk blocks, 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`.
|
||||
@@ -42,7 +42,7 @@ Everything written — chat, commit messages, comments, docs, code — is in **E
|
||||
|
||||
Write the thing, not an introduction to it. State what holds and stop; name a rejected alternative only where that stops a reader choosing it.
|
||||
|
||||
Write negations as people say them. BANNED: `stops nothing`, `changes nothing`, `reveals nothing`, `depends on no one`. GOOD: `doesn't stop anything`, `doesn't change anything`, `doesn't reveal anything`, `doesn't depend on anyone`.
|
||||
Write negations as people say them, with any verb. BANNED: `stops nothing`, `changes nothing`, `costs nothing`, `reveals nothing`, `depends on no one`, `so answering in time costs nothing`. GOOD: `doesn't stop anything`, `doesn't change anything`, `doesn't cost anything`, `doesn't reveal anything`, `doesn't depend on anyone`, `so answering doesn't cost anything`.
|
||||
|
||||
Reviewers hold prose to the full rules, with examples: `~/.claude/skills/larv-review/standards/prose.md`.
|
||||
|
||||
|
||||
@@ -18,7 +18,7 @@ You are an elite stability-focused code reviewer with deep expertise in defensiv
|
||||
- *Breadth:* every hunk in every changed file, no skimming. Track which files you have covered; batch large diffs, never truncate the review.
|
||||
- *Depth:* trace the riskiest data paths end-to-end (input → logic → persistence/response), the interactions between changed pieces, and between the change and config (timeout hierarchies, retries × idempotency, queue worker counts, env parity).
|
||||
- *Absences:* what should be in this diff but isn't — un-updated callers (grep every changed or renamed public symbol), missing migration for a model change, missing authz on a new path, missing tests, un-regenerated OpenAPI/docs, stale README/AGENTS.md, and deletions the change obsoletes but didn't make.
|
||||
- Repeat a targeted pass over the riskiest files; stop only when a pass yields nothing new.
|
||||
- Repeat a targeted pass over the riskiest files; stop only when a pass doesn't find anything new.
|
||||
|
||||
## Review Focus Areas
|
||||
|
||||
|
||||
@@ -127,7 +127,7 @@ You review the seams that make verification possible and the strategy that uses
|
||||
- **The pyramid follows the boundaries.** Coverage is end-to-end; the pyramid decides at which layer. Each suite earns its existence by naming the failure class only it can catch and its time and determinism budget — how fast it must run and how hermetic it must be. Core logic at the bottom, real-adapter integration at the seams (the actual DB, the actual queue) in the middle, a thin hermetic e2e layer (owned clock, seeded data, faked third parties) proving the wiring on a handful of critical journeys — an e2e failure is a deployment signal, not the primary bug detector. Anything testable at a cheaper layer moves down; an inverting pyramid signals boundaries the design failed to provide. A flaky test is a missing seam and a finding, never a retry policy. Prefer sociable tests with fakes over mock-heavy solitary ones — a suite that only passes by mocking internals is pinning structure, not behavior: the missing-seam smell again.
|
||||
- **Concurrency is testable or it is untested.** Name every place two flows touch shared state, the invariant that serializes each (transaction, queue, idempotency key, ordering guarantee), and how a test forces the interleaving. A race reachable only by stress-looping is a missing seam — flag the seam as the finding; probabilistic runs are scheduled, never gating.
|
||||
- **The external contract is executably pinned.** Contract tests fail when a published shape breaks — the lock on that one-way door. Price them like the versioning machinery (The External Contract): zero consumers outside your control, defer; many, mandatory.
|
||||
- **Load targets come from Stage 0.** Load and performance tests verify the recorded scale numbers; no recorded scale, nothing to verify — fix Stage 0 first (a rig for unrecorded load is "Hunt the imagined requirement" wearing a QA hat). Data and traffic are production-shaped — a load run against a 1000-row database measures nothing. Runs are scheduled outside the merge gate (see Delivery); determinism here means a repeatable method against fixed thresholds, not identical latencies.
|
||||
- **Load targets come from Stage 0.** Load and performance tests verify the recorded scale numbers; no recorded scale, nothing to verify — fix Stage 0 first (a rig for unrecorded load is "Hunt the imagined requirement" wearing a QA hat). Data and traffic are production-shaped — a load run against a 1000-row database doesn't measure anything. Runs are scheduled outside the merge gate (see Delivery); determinism here means a repeatable method against fixed thresholds, not identical latencies.
|
||||
- **Post-deploy production suites are a designed capability.** Tagged, idempotent synthetic traffic against external surfaces only (API, UI), built once and run twice: post-deploy smoke and scheduled monitoring. It asserts liveness of the deployed surface, not logic — logic determinism lives in the pre-merge suites. Self-cleaning means expendable-by-design: a synthetic tenant or TTL-tagged data reaped out-of-band, never teardown-in-the-test, and never a delete endpoint added to the contract only for tests. Side effects are sandboxed by design — a synthetic checkout must never charge a real card — and the synthetic marking propagates through every downstream sink (telemetry, billing, analytics) so real signals stay uncontaminated; a tag that dies at the API edge is a missing seam.
|
||||
|
||||
## Delivery (the path to production is architecture)
|
||||
|
||||
@@ -9,5 +9,6 @@ Everything written — chat, commit messages, comments, docs, code — is in **E
|
||||
3. **Default to delete.** Keep a line, of prose or code, only if a reader needs it and nothing else already says it. Adding words is a deliberate act: name what a reader could not understand without them.
|
||||
4. **Short.** Cut whatever does not clearly help 1–3.
|
||||
|
||||
- **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.
|
||||
- **Write the thing, not an introduction to it.** A sentence announcing what follows, or flagging that it deserves attention, doesn't carry anything — 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.
|
||||
- **Write negations as people say them, with any verb.** A verb with `nothing` or `no one` as its object is a 🟡. BANNED: `stops nothing`, `changes nothing`, `costs nothing`, `reveals nothing`, `depends on no one`, `so answering in time costs nothing`. GOOD: `doesn't stop anything`, `doesn't change anything`, `doesn't cost anything`, `doesn't reveal anything`, `doesn't depend on anyone`, `so answering doesn't cost anything`.
|
||||
- **No contrastive tail.** `X rather than Y`, `not Y but X`, `instead of Y`: state X and stop. The rejected alternative is noise unless naming it stops a reader choosing Y. BANNED: `verified in CI rather than asserted`. GOOD: `verified in CI`.
|
||||
|
||||
Reference in New Issue
Block a user