Promote two rules into memory.md: question the issue, cut the comments #72

Merged

vnprc merged 1 commit from agent/promote-comment-and-question-rules into master

2026-09-29 04:43:53 +01:00

allod-agent commented

2026-09-29 04:35:57 +01:00

Member

Two rules move from the ledger into memory.md, where every session reads them: question an issue before building it, and cut a diff's comments before its pull request opens. Each has sightings from two separate sessions, which is the bar for the index.

What changes for a running machine: nothing. These are instructions to agents.
What stays identical: every other line of memory. memory.md grows from 8639 to 9281 bytes, under its 16384 cap.
What proves it: .hooks/memory-budget --worktree passes. The quotes below are the evidence for each rule.
If it is wrong: revert this pull request. The four ledger lines it removes come back with it.

Edit 1: question the issue before building it

memory.md gains a section, Before the First Edit, with one line. agent-behavior.md, Scope Discipline, gains the fuller statement.

Before building an issue as written, state the need in one sentence and the smallest change that meets it, and name what each feature saves the owner. An issue is its author's proposal, not a decision: when a smaller change meets the need, say so before the first edit, not after the pull request.

Sightings:

claude 1efe7fa4-aa2d-40de-8c9e-48f7f1a4223f: "seems like a lot of complexity to paper over issues that could be resolved other ways. what are we building for exactly?"
claude b76e0d49-e219-4b4f-8602-f3738ae972da: "it seems simpler to me to just require the port in the registry and be done with all this random port selection complexity"

Edit 2: cut comments before the pull request opens

memory.md, PR Workflow, gains one line. writing.md, Code comments, gains one bullet. The rule already existed in writing.md and was not followed in either session, so this is a sharper trigger and a named owner for the step, not a new rule.

Before a PR opens, cut every comment its diff adds down to a contract, a trap or a pointer, in one to three lines, and delete the rest. The integrator does this itself after the last fix round: a worker's or a reviewer's trim stops at shorter.

Sightings:

claude 65544cc3-0545-4ee4-a93a-41ff09331efa: "what's with the wall of text comment in checks/pi-provider-lifecycle.nix? is all that necessary? are we adhering to the new comment policy?"
claude b76e0d49-e219-4b4f-8602-f3738ae972da: "cut down the verbose comments in allod/archetypes#120" and, of the next pull request, "i'm sure it will have the same issue"

Ledger

The four sightings above are removed from ledger.md, since the rules they argue for have landed. The seven other sightings from these sessions stay, each with one session behind it.

How this was made

By hand, at the owner's request, applying the memory-backpass skill's gates: two sessions per index line, a verbatim quote per edit, the index within its cap. The skill itself was not run. It needs a traces checkout and the private memory, and this machine has neither.

Risk

R0. Documentation for agents; no runtime behaviour.

Two rules move from the ledger into `memory.md`, where every session reads them: question an issue before building it, and cut a diff's comments before its pull request opens. Each has sightings from two separate sessions, which is the bar for the index. - **What changes for a running machine:** nothing. These are instructions to agents. - **What stays identical:** every other line of memory. `memory.md` grows from 8639 to 9281 bytes, under its 16384 cap. - **What proves it:** `.hooks/memory-budget --worktree` passes. The quotes below are the evidence for each rule. - **If it is wrong:** revert this pull request. The four ledger lines it removes come back with it. ## Edit 1: question the issue before building it `memory.md` gains a section, Before the First Edit, with one line. `agent-behavior.md`, Scope Discipline, gains the fuller statement. > Before building an issue as written, state the need in one sentence and the smallest change that meets it, and name what each feature saves the owner. An issue is its author's proposal, not a decision: when a smaller change meets the need, say so before the first edit, not after the pull request. Sightings: - claude `1efe7fa4-aa2d-40de-8c9e-48f7f1a4223f`: "seems like a lot of complexity to paper over issues that could be resolved other ways. what are we building for exactly?" - claude `b76e0d49-e219-4b4f-8602-f3738ae972da`: "it seems simpler to me to just require the port in the registry and be done with all this random port selection complexity" ## Edit 2: cut comments before the pull request opens `memory.md`, PR Workflow, gains one line. `writing.md`, Code comments, gains one bullet. The rule already existed in `writing.md` and was not followed in either session, so this is a sharper trigger and a named owner for the step, not a new rule. > Before a PR opens, cut every comment its diff adds down to a contract, a trap or a pointer, in one to three lines, and delete the rest. The integrator does this itself after the last fix round: a worker's or a reviewer's trim stops at shorter. Sightings: - claude `65544cc3-0545-4ee4-a93a-41ff09331efa`: "what's with the wall of text comment in `checks/pi-provider-lifecycle.nix`? is all that necessary? are we adhering to the new comment policy?" - claude `b76e0d49-e219-4b4f-8602-f3738ae972da`: "cut down the verbose comments in allod/archetypes#120" and, of the next pull request, "i'm sure it will have the same issue" ## Ledger The four sightings above are removed from `ledger.md`, since the rules they argue for have landed. The seven other sightings from these sessions stay, each with one session behind it. ## How this was made By hand, at the owner's request, applying the `memory-backpass` skill's gates: two sessions per index line, a verbatim quote per edit, the index within its cap. The skill itself was not run. It needs a traces checkout and the private memory, and this machine has neither. ## Risk R0. Documentation for agents; no runtime behaviour.

allod-agent added 1 commit

2026-09-29 04:35:57 +01:00

Promote two rules from the ledger into the index a8fdaa22e0

Question an issue before building it, and cut a diff's comments before
its pull request opens. Each has sightings from two sessions. The four
sightings leave the ledger with them.