@erclx/canon 5.37.0 → 5.39.0

package/claude/skills/review-address/SKILL.md

@@ -7,13 +7,14 @@ metadata:
 
 # Review address
 
-The worker's half of the review channel. `review-pr` posts findings to
-the PR from an independent session. This skill consumes them: fix, reply, push.
+The worker's half of the review channel. `review-pr` posts findings to the PR from an independent session. This skill consumes them: fix, reply, push.
 
 ## Guards
 
-- Resolve `<number>` and `<tip>` off `canon pr head --json`. An `ambiguous-pull` refusal stops: `❌ Two open PRs on this branch. Name the one to address.` A record with no `number` takes the lookup in `${CLAUDE_SKILL_DIR}/references/rest-reads.md`. Nothing resolving stops: `❌ No open PR. Nothing to address.`
-- If the PR has no review comments or threads, run step 5's staleness test before deciding. A branch that passes both of its halves stops here: `✅ No review findings to address.` One that fails either skips steps 1 through 4 and runs step 5 onward, since a branch goes stale from `main` moving and a closed review says nothing about whether it still merges.
+- Resolve `<number>` and `<tip>` off `canon pr head --json`. An `ambiguous-pull` refusal stops: `❌ Two open PRs on this branch. Name the one to address.`
+- A record with no `number` takes the lookup in `${CLAUDE_SKILL_DIR}/references/rest-reads.md`. Nothing resolving stops: `❌ No open PR. Nothing to address.`
+- If the PR has no review comments or threads, run step 5's staleness test before deciding. A branch passing both halves stops here: `✅ No review findings to address.`
+- A branch failing either half skips steps 1 through 4 and runs step 5 onward, since a branch goes stale from `main` moving and a closed review says nothing about whether it still merges
 - Fix findings. Do not merge.
 
 ## Step 1: pull the review findings and CI status
@@ -26,30 +27,32 @@ Also read the CI check status so the fixes cover failing checks, not only review
 canon pr checks <number> --json
 ```
 
-Read the verdict off the record's `state` rather than off the exit. Treat `failing` as a finding to resolve alongside the review comments. A `pending` covers a tip whose runs have yet to conclude and a tip carrying no run at all, which the record separates on `matched`, and neither is a green to continue on. A record carrying `conflicted: true` is a third case: the branch conflicts with its base, so no run will start and the wait never ends. Stop and report it, since a rebase is the repair. When no record comes back at all, read the check runs on the tip through `${CLAUDE_SKILL_DIR}/references/rest-reads.md`.
+Read the verdict off the record's `state` rather than off the exit.
+
+| Record             | Means                                                                                                       |
+| ------------------ | ----------------------------------------------------------------------------------------------------------- |
+| `failing`          | A finding to resolve alongside the review comments                                                          |
+| `pending`          | Runs not concluded, or no run on the tip, which `matched` separates. Neither is a green to continue on.     |
+| `conflicted: true` | The branch conflicts with its base, so no run will start. Stop and report it, since a rebase is the repair. |
+| No record          | Read the check runs on the tip through `${CLAUDE_SKILL_DIR}/references/rest-reads.md`                       |
 
 ## Step 2: address each finding
 
-For each finding, implement the fix in the working tree. When a finding is a
-question or a conscious-accept rather than a defect, note the reply text instead
-of editing. Handle each finding independently. Do not let one unresolved finding
-block the others.
+For each finding, implement the fix in the working tree. When a finding is a question or a conscious-accept rather than a defect, note the reply text instead of editing. Handle each finding independently, so one unresolved finding blocks no other.
 
 ## Step 3: verify
 
-Run the project check (`bun run check` or the project's documented equivalent).
-Do not push a red follow-up.
+Run the project check (`bun run check` or the project's documented equivalent). Do not push a red follow-up.
 
 ## Step 4: refresh stale docs
 
-The fixes may have changed or added behavior that `.claude/` context entries or docs describe. Refresh them with the `context-fold` skill, which maps the changed files to the entries that reference them and rewrites the stale sections. Do not reimplement that mapping here. When a fix adds a new capability with no existing entry, `context-fold` flags it rather than creating one.
+The fixes may have changed behavior that `.claude/` context entries or docs describe. Refresh them with the `context-fold` skill, which maps changed files to the entries citing them and rewrites the stale sections.
+
+Do not reimplement that mapping here. When a fix adds a capability with no existing entry, `context-fold` flags it rather than creating one.
 
 ## Step 5: rebase a stale branch
 
-A branch goes stale from `main` moving rather than from anything the branch did,
-so the test runs on every invocation, including the one the second guard sends
-straight here with no findings to fix. Fetch first. A stale local `origin/main`
-reports no conflict on a branch that has one.
+A branch goes stale from `main` moving rather than from anything it did, so the test runs on every invocation, including one the guard sends straight here. Fetch first, since a stale local `origin/main` reports no conflict on a branch that has one.
 
 ```bash
 git fetch origin main
@@ -59,114 +62,59 @@ git diff -z --name-only --no-renames "$fork" HEAD |
   xargs -0 -r git --literal-pathspecs diff --name-only --no-renames "$fork" origin/main --
 ```
 
-`merge-tree` exiting non-zero means the branch no longer merges, and a path the
-last command prints means `main` changed a file it writes after it branched, so
-its green run tested a merge nobody will make. Even a clean merge can hide
-semantic conflicts, per Fowler's [Mainline Integration](https://martinfowler.com/articles/branching-patterns.html#mainline-integration),
-so either one sends the branch to `${CLAUDE_SKILL_DIR}/references/rebase-conflicts.md`
-for the sequence, the conflict rules, and the check to re-run. When that check
-fails after a clean rebase, the failure is the semantic conflict, fixed on the
-branch like any other. Neither firing skips to step 6, which covers a `main` that
-moved only on files the branch does not write.
-
-`git merge-tree` reads committed history, so this test says nothing about the
-fixes still sitting in the working tree. A branch that merges clean as committed,
-whose fixes touch lines `main` moved, passes here and reaches the remote
-unmergeable. Step 6 re-runs the test once those fixes are commits.
+### Reading the test
+
+`merge-tree` exiting non-zero means the branch no longer merges. A path the last command prints means `main` changed a file the branch writes, so its green run tested a merge nobody will make.
+
+- Either one sends the branch to `${CLAUDE_SKILL_DIR}/references/rebase-conflicts.md` for the sequence, the conflict rules, and the check to re-run
+- Even a clean merge can hide semantic conflicts, per Fowler's [Mainline Integration](https://martinfowler.com/articles/branching-patterns.html#mainline-integration). A check failing after a clean rebase is one, fixed on the branch.
+- Neither firing skips to step 6, which covers a `main` that moved only on files the branch does not write
+
+`git merge-tree` reads committed history, so it says nothing about fixes still in the working tree. Step 6 re-runs the test once those fixes are commits.
 
 ## Step 6: push, then reply
 
-Push the fixes before posting the reply so the comment never runs ahead of the
-code it describes. Ship the fixes as a follow-up commit on the same branch with
-the `git-followup` skill, invoked with `reply-owned` so it stages, commits,
-pushes, and refreshes the open PR body without posting its own comment. This
-skill owns the reply. Do not reimplement that flow here.
-
-`git-followup` syncs the body and title against the fix commit on every
-invocation, including `reply-owned`, so the merge record reflects what this pass
-changed rather than only what opened the PR. The reply comment still carries the
-fix log mapped to each finding, since the two serve different readers: the body
-is the merge record and the reply is the review's own thread. A rebase in step 5
-rewrote the branch, so that push is a force-push and `git-followup` resolves it
-from the tracking branch. Worker branches are single-owner here, which is what
-makes overwriting the remote safe.
-
-`git-followup` stops on an unchanged tree. A run that answered every finding as a
-conscious-accept and whose rebase left the generated files alone has nothing for
-it to commit, so the rebase would never reach the remote. Push that case directly
-with `git push --force-with-lease`, then post the reply below.
-
-Once the fixes are commits, re-run step 5's staleness test against the new head.
-A conflict that appears only now is one the fixes introduced against lines `main`
-moved, which the earlier test could not see. Rebase again under
-`${CLAUDE_SKILL_DIR}/references/rebase-conflicts.md` and force-push, then
-continue. The second push costs one extra force-push in a
-case that needs the fix and the sibling to touch the same lines.
-
-Then write a summary reply to `.canon/tmp/pr/reply/reply-<number>.md`
-mapping each finding to what changed, or to a one-line reason when it is a
-conscious-accept rather than a defect. Key the filename on the PR number so two
-sessions addressing different pull requests never overwrite each other between
-the write and the post. Note any `.claude/` docs refreshed as a result of the
-fixes.
-
-The reply is a rendered-for-human GitHub surface, so load the `write-human`
-skill for voice and word choice, follow
-`${CLAUDE_SKILL_DIR}/../markdown-craft/references/markdown.md` for punctuation, and keep each
-mapping to a line or two.
-
-Open the body with the `## Review response` heading so it anchors as a section
-distinct from human threads and stays subordinate to the `## Review` heading the
-review itself carries. Follow it with a one-line summary sentence, then one
-bullet per finding, each opening with the bolded finding identifier.
-Close the body with `🤖 Addressed by Claude Code` on its own line so the reply
-reads as an independent machine pass, not a human sign-off.
-
-A finding this run declined carries the fact that settled it, inside its own
-bullet rather than in a section of its own. Name the plan question that already
-answered it, the constraint the diff does not show, or the measurement the
-reviewer did not have. Answering the dispatch in the channel and leaving that
-fact there loses it when both sessions end, and the reviewer is left with a
-finding that stopped being mentioned. The rule fires on a bullet the body already
-writes, so nothing depends on judging mid-reply whether a reply was important.
-
-The rule reaches a finding and nothing else. A correction to what the reviewing
-session believes about the world, such as which session holds which branch or
-what an edit passes through before it lands, changes no finding on this pull
-request and belongs in that session's own record rather than on a thread that
-closes. Keep it off the comment, and answer it wherever the dispatch reached this
-session when one did. Nothing tests the reply for either rule, since the scan
-below reads it for banned characters and phase labels alone, so both halves hold
-while a run applies them.
-
-The `pull_request` check the git-pr surface carries reads a pull request's own
-title and body, not a reply comment, so the scan below stays the only gate here.
-
-When step 5 rebased the branch, say so in the summary sentence and name which
-files were resolved by hand and which the regen rebuilt. The next review is a
-full pass rather than a delta, and the reader is owed the reason.
-
-A run the second guard sent straight to step 5 has no findings to map, so it
-takes a different body rather than an empty list. Open it with `## Rebase`, not
-`## Review response`, since nothing on the pull request is being responded to and
-that heading claims a review this run never read. State which half of the test
-fired, being a branch that stopped merging or one `main` changed files under,
-name what landed on `main`, name the files resolved by hand and those
-the regen rebuilt, and close the same way. The heading stays outside the
-`## Review` family so the close-out's equality test on the first line never
-matches it.
-
-Before posting, follow `${CLAUDE_SKILL_DIR}/../git-pr/references/publish.md`
-and run its scan against the reply:
+Push the fixes before posting the reply, so the comment never runs ahead of the code it describes. Ship them as a follow-up commit with `git-followup`, invoked with `reply-owned` so it stages, commits, pushes, and refreshes the PR body without its own comment.
+
+### What the push carries
+
+This skill owns the reply, so do not reimplement the followup flow here.
+
+- `git-followup` syncs the body and title on every invocation, `reply-owned` included, so the merge record reflects this pass. The reply still maps fixes to findings in the review's own thread.
+- A rebase in step 5 rewrote the branch, so the push is a force-push `git-followup` resolves from the tracking branch. Worker branches are single-owner, which makes that safe.
+- `git-followup` stops on an unchanged tree, as when every finding was a conscious-accept and the rebase left generated files alone. Push that with `git push --force-with-lease`.
+
+Once the fixes are commits, re-run step 5's staleness test against the new head. A conflict appearing only now is one the fixes introduced against lines `main` moved, so rebase again under `${CLAUDE_SKILL_DIR}/references/rebase-conflicts.md` and force-push.
+
+### Write the reply
+
+Write a summary reply to `.canon/tmp/pr/reply/reply-<number>.md`, keyed on the PR number so two sessions addressing different pull requests never overwrite each other. Load `write-human` for voice, follow `${CLAUDE_SKILL_DIR}/../markdown-craft/references/markdown.md`, and keep each mapping to a line or two.
+
+| Part     | Content                                                                                                                                        |
+| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| Heading  | `## Review response`, distinct from human threads and subordinate to the review's own `## Review`                                              |
+| Summary  | One sentence. After a step 5 rebase, say so and name files resolved by hand and those the regen rebuilt, since the next review is a full pass. |
+| Findings | One bullet per finding, opening with the bolded identifier, naming what changed or a one-line reason for a conscious-accept                    |
+| Docs     | Any `.claude/` docs refreshed as a result of the fixes                                                                                         |
+| Close    | `🤖 Addressed by Claude Code` on its own line, so the reply reads as a machine pass rather than a human sign-off                               |
+
+A run the guard sent straight to step 5 has no findings to map, so it takes the `## Rebase` body in `${CLAUDE_SKILL_DIR}/references/rebase-only.md` instead. A run with findings skips that file.
+
+### What a declined finding carries
+
+A finding this run declined carries the fact that settled it inside its own bullet, such as the plan question that answered it, a constraint the diff does not show, or a measurement the reviewer lacked. Left in the channel, that fact is lost when both sessions end.
+
+The rule reaches a finding and nothing else. A correction to what the reviewing session believes about the world changes no finding here, so answer it wherever the dispatch reached this session and keep it off the comment.
+
+### Scan and post
+
+Nothing tests the reply for either rule above. Follow `${CLAUDE_SKILL_DIR}/../git-pr/references/publish.md` and run its scan, which reads for banned characters and phase labels alone:
 
 ```bash
 canon labels scan --body-file .canon/tmp/pr/reply/reply-<number>.md
 ```
 
-The hook skips `.canon/tmp/`, so this scan is the only gate on the published
-reply. Fix any hit the standard names, then post the reply to the PR and
-keep the `id` the POST answers with, since Step 7 edits this exact comment rather
-than trusting whichever one `gh` considers last:
+The hook skips `.canon/tmp/`, and the `pull_request` check reads only a pull request's own title and body, so this scan is the only gate on the reply. Fix any hit, then post and keep the `id` the POST answers with, since Step 7 edits this exact comment:
 
 ```bash
 gh api -X POST 'repos/{owner}/{repo}/issues/<number>/comments' -F body=@.canon/tmp/pr/reply/reply-<number>.md --jq .id > .canon/tmp/pr/reply/reply-<number>.id
@@ -174,39 +122,26 @@ gh api -X POST 'repos/{owner}/{repo}/issues/<number>/comments' -F body=@.canon/t
 
 ## Step 7: confirm resolution
 
-After the push, read Watching CI in `${CLAUDE_SKILL_DIR}/../git-ship/SKILL.md`
-without invoking that skill, start its background watch, end the turn on its
-line, and run the rest of this step and Step 8 on the wake. Reuse a watch
-already running on this PR, since it reads the new tip. On the wake, stop on `conflicted` naming a rebase, on a `reason` naming it,
-and on a timeout reporting CI unsettled. When every finding is addressed and
-the state is `passing`, append
-the closing confirmation to the reply file Step 6 already posted, so the thread
-carries one terminal state rather than a second comment under no heading:
+After the push, read Watching CI in `${CLAUDE_SKILL_DIR}/../git-ship/SKILL.md` without invoking that skill, start its background watch, end the turn on its line, and run the rest of this step and Step 8 on the wake. Reuse a watch already running on this PR, since it reads the new tip.
 
-```bash
-printf '\n✅ All review findings addressed, CI green.\n' >> .canon/tmp/pr/reply/reply-<number>.md
-```
+- On the wake, stop on `conflicted` naming a rebase, on a `reason` naming it, and on a timeout reporting CI unsettled
+- If any check fails, skip the edit and report the failing check so it can be fixed first
 
-A rebase-only run addressed no finding, so it appends its own confirmation
-instead of that one. Claiming findings were addressed on a pull request that
-carries none is false on a surface nothing else checks:
+When every finding is addressed and the state is `passing`, append the closing confirmation to the reply file Step 6 posted, so the thread carries one terminal state rather than a second comment. A rebase-only run appends the line `${CLAUDE_SKILL_DIR}/references/rebase-only.md` gives instead.
 
 ```bash
-printf '\n✅ Rebased onto origin/main, CI green. No review findings were open.\n' >> .canon/tmp/pr/reply/reply-<number>.md
+printf '\n✅ All review findings addressed, CI green.\n' >> .canon/tmp/pr/reply/reply-<number>.md
 ```
 
-Re-run the scan against the updated file, since the appended line is new
-content the Step 6 scan never saw:
+Re-run the scan against the updated file, since the appended line is new content the Step 6 scan never saw:
 
 ```bash
 canon labels scan --body-file .canon/tmp/pr/reply/reply-<number>.md
 ```
 
-Then edit the exact comment Step 6 posted, read back from the id it saved,
-rather than posting a second comment. A shell variable assigned from `cat` and
-handed to `gh` still carries a runtime value the isolation rule cannot verify,
-so read the id as its own plain command and write the printed value as a
-literal in the `gh api` call rather than a substitution or a variable:
+### Edit the posted comment
+
+Edit the exact comment Step 6 posted, read back from the id it saved, rather than posting a second one. A shell variable assigned from `cat` still carries a runtime value the isolation rule cannot verify, so print the id and write it as a literal:
 
 ```bash
 cat .canon/tmp/pr/reply/reply-<number>.id
@@ -217,18 +152,9 @@ gh api -X PATCH "repos/{owner}/{repo}/issues/comments/<id printed above>" \
   -F body=@.canon/tmp/pr/reply/reply-<number>.md
 ```
 
-`--edit-last` was the first shape and it targets the wrong object here.
-It edits the last comment posted by the authenticated user, not the last
-comment this run posted, and every session here authenticates as the one
-account the operator also comments from. A comment the operator leaves on
-their own pull request during the minutes Step 7 spends waiting on CI becomes
-that last comment, so `--edit-last` would overwrite it with the reply and the
-confirmation, silently. Targeting the id Step 6 captured closes that whether
-or not anyone commented in between.
+Never use `--edit-last`, which edits the last comment the authenticated account posted. The operator comments from that same account, so a comment they leave during the CI wait would be silently overwritten.
 
-If any check fails, skip the edit. Report the failing check so it can be fixed
-first. This is a resolution signal, not a formal approval, since the PR author
-cannot approve their own PR.
+This is a resolution signal, not a formal approval, since the PR author cannot approve their own PR.
 
 ## Step 8: output
 
@@ -237,15 +163,7 @@ Addressed <N> findings on PR #<number>. Follow-up pushed.
 <Rebased onto origin/main. <N> files resolved by hand, <N> rebuilt by the check.>
 ```
 
-Omit the second line when the branch still merged. Name any finding left as a
-reply rather than a code change, with its one-line reason.
-
-A rebase-only run drops the first line rather than reporting zero findings
-addressed, and leads with the rebase instead:
-
-```plaintext
-Rebased PR #<number> onto origin/main. <N> files resolved by hand, <N> rebuilt by the check.
-```
+Omit the second line when the branch still merged. Name any finding left as a reply rather than a code change, with its one-line reason. A rebase-only run reports the line `${CLAUDE_SKILL_DIR}/references/rebase-only.md` gives instead.
 
 Do not merge. Hand back to the reviewer for re-review, or to the orchestrator where no live reviewer answers.
 

package/claude/skills/review-address/references/rebase-only.md

@@ -0,0 +1,34 @@
+---
+title: Rebase-only run
+description: The reply body, closing confirmation, and output line review-address takes when its guard sent it straight to the rebase with no review findings to map
+---
+
+# Rebase-only run
+
+Read from Steps 6, 7, and 8 of `review-address` when the second guard sent the run straight to step 5 with no findings open. A run carrying findings skips this file.
+
+## Reply body
+
+A rebase-only run has no findings to map, so it takes a different body rather than an empty list. Open it with `## Rebase`, since nothing on the pull request is being responded to and `## Review response` claims a review this run never read.
+
+- State which half of the staleness test fired, being a branch that stopped merging or one `main` changed files under
+- Name what landed on `main`, then the files resolved by hand and those the regen rebuilt
+- Close with `🤖 Addressed by Claude Code` on its own line, the same as a review response
+
+The heading stays outside the `## Review` family, so the close-out's equality test on the first line never matches it.
+
+## Closing confirmation
+
+Claiming findings were addressed on a pull request carrying none is false on a surface nothing else checks. Append this line at Step 7 in place of the findings confirmation, then re-run the scan:
+
+```bash
+printf '\n✅ Rebased onto origin/main, CI green. No review findings were open.\n' >> .canon/tmp/pr/reply/reply-<number>.md
+```
+
+## Output
+
+Drop the findings line rather than reporting zero findings addressed, and lead with the rebase:
+
+```plaintext
+Rebased PR #<number> onto origin/main. <N> files resolved by hand, <N> rebuilt by the check.
+```

package/claude/skills/review-craft/SKILL.md

@@ -7,7 +7,7 @@ metadata:
 
 # Review craft
 
-A review with no stated axes reads the changed lines for bugs and stops there. What breaks in a consumer the diff never opened, a doc the change made false a section away from its hunk, or a screenshot showing the opposite of what a ticked box claims all go unread. This skill carries the judgment: what to look for, in what order, and how sure to be before calling it a finding.
+A review with no stated axes reads the changed lines for bugs and stops there. A broken consumer the diff never opened, a doc made false a section from its hunk, or a screenshot contradicting a ticked box all go unread. This skill carries what to look for, in what order, and how sure to be.
 
 The procedure that loaded this skill owns everything else: which files to read, the filter that decides what gets reported, the severity ladder, and where the report goes. Nothing here grades a finding or posts one.
 
@@ -27,21 +27,35 @@ A risky claim resting on assertion alone is where the review spends its reading.
 
 An axis whose condition the diff meets is not optional. When the security or the rendered output axis names a reference and its condition holds, read that reference before moving to the next axis, however clear the diff looks without it.
 
-1. **Design and scope.** Does the change do one thing, is it more complex than the problem needs, and does it build what nobody asked for? State a design finding as a concrete cost, such as a second path nobody calls, a layer with one caller, or a flag no caller passes, never as a preference. Walk it in the order `Walk the design` below gives.
+1. **Design and scope.** Does the change do one thing, is it more complex than the problem needs, and does it build what nobody asked for? Walk it in the order `Walk the design` below gives.
+   - State a design finding as a concrete cost, such as a second path nobody calls, a layer with one caller, or a flag no caller passes, never as a preference
 2. **Correctness and edge cases.** The empty input, the boundary value, the refused call, the second run, the concurrent run, and the error path a caller actually meets.
-3. **What breaks outside the diff.** List every consumer of a changed contract, whether a function signature, a file format, a flag, an output shape, or a heading another tool matches, and check the change against each one. Then list each behavior the diff removes or changes, such as a guard, a refusal, a default, or an output, and search every doc the diff touches, in full rather than at the hunk, for a sentence still promising the old behavior. File that sentence as a finding against the doc, quoting it and naming its section, since the doc is what goes wrong for the next reader.
+3. **What breaks outside the diff.** List every consumer of a changed contract and check the change against each one.
+   - A contract is a function signature, a file format, a flag, an output shape, or a heading another tool matches
+   - List each behavior the diff removes or changes, such as a guard, a refusal, a default, or an output
+   - Search every doc the diff touches, in full rather than at the hunk, for a sentence still promising the old behavior
+   - File that sentence against the doc, quoting it and naming its section, since the doc is what misleads the next reader
 4. **Tests.** Hand each test the change adds or edits to `canon:test-craft` and its final filter. Report it rather than proceeding silently when that skill does not resolve.
-5. **Guard the bar.** A change can pass by lowering its own bar: a threshold moved, a test skipped, deleted, or emptied of assertions, an inline suppression, a path dropped from a lint or type run, a stub that throws or an empty catch where behavior was promised, or a new config exception. Each is a finding unless the diff says why, and a suppression whose stated reason holds is the author's call.
-6. **Performance.** A query or a remote call inside a loop, a read with no bound on its size, and a list endpoint with no pagination. A claimed speedup needs a before and an after measured the same way and repeated past run-to-run noise. One run on each side is an anecdote, and a result inside the noise argues for reverting the added complexity.
+5. **Guard the bar.** A change can pass by lowering its own bar. Each lowering is a finding unless the diff says why, and a suppression whose stated reason holds is the author's call.
+   - A threshold moved, or a test skipped, deleted, or emptied of assertions
+   - An inline suppression, a path dropped from a lint or type run, or a new config exception
+   - A stub that throws or an empty catch where behavior was promised
+6. **Performance.** A query or a remote call inside a loop, a read with no bound on its size, and a list endpoint with no pagination.
+   - A claimed speedup needs a before and an after measured the same way and repeated past run-to-run noise
+   - One run on each side is an anecdote, and a result inside the noise argues for reverting the added complexity
 
 ### Axes a condition opens
 
 Read each of these when the diff reaches what it names.
 
-7. **Security.** Read `${CLAUDE_SKILL_DIR}/references/security.md` when the diff runs a command, writes or deletes a file, handles input from outside the process, touches a secret, adds a dependency, or changes a default a consumer installs.
-8. **Rendered output.** Read `${CLAUDE_SKILL_DIR}/references/ui.md` when the diff touches a file that paints, such as markup, a stylesheet, a component, a template, or a design token, or when the pull request carries an evidence comment. A finding read off a stylesheet diff says what the author changed, and only the screenshot says what a user sees, so the reference opens the images and checks whether any exist.
-9. **Developer experience and operations.** Ports, hooks, scripts, config, and scaffold defaults a consumer installs. A new required step nobody documented, a default that fails on a clean machine, or a hook that slows every commit is a finding even when the code is correct.
-10. **Executable prose.** A skill body, a rule, or a prompt is instructions a model runs. Read it the way you read code: a step that races another, a precondition it never states, a branch with no exit, and two instructions that contradict each other are bugs.
+7. **Security.** Read `${CLAUDE_SKILL_DIR}/references/security.md` when the diff runs a command, writes or deletes a file, takes outside input, touches a secret, adds a dependency, or changes a default.
+8. **Rendered output.** Read `${CLAUDE_SKILL_DIR}/references/ui.md` when the diff touches a file that paints, or when the pull request carries an evidence comment.
+   - A file that paints is markup, a stylesheet, a component, a template, or a design token
+   - A stylesheet diff says what the author changed and only the screenshot says what a user sees, so the reference opens the images and checks whether any exist
+9. **Developer experience and operations.** Ports, hooks, scripts, config, and scaffold defaults a consumer installs.
+   - A new required step nobody documented, a default that fails on a clean machine, or a hook that slows every commit is a finding even when the code is correct
+10. **Executable prose.** A skill body, a rule, or a prompt is instructions a model runs, so read it the way you read code.
+    - A step that races another, a precondition it never states, a branch with no exit, and two instructions that contradict each other are bugs
 
 ### Walk the design
 
@@ -50,7 +64,7 @@ Walk the design axis in this order, and skip a step the change gives nothing to
 1. Name the next change this code is likely to need, and count the files and units it would touch. A count that grows with each new case is the cost to report.
 2. State what each new unit hides from its callers. A unit that passes its arguments straight through to another hides nothing and is a layer with no work.
 3. Find each rule or constant the change states, and check that it lives in one place. The same rule in two places drifts the first time one copy changes.
-4. Look for a parameter that switches what a function does, a chain of calls reaching through one object into another, and a read or write of global state. Each ties a caller to internals it should not know.
+4. Look for a parameter that switches what a function does, a call chain reaching through one object into another, and a read or write of global state. Each ties a caller to internals.
 5. Ask each changed file for its one reason to change. A file that two unrelated requests would both edit carries two concerns.
 6. List what the code reads without being handed it, such as the clock, the environment, the filesystem, or a random source. A hidden input is what makes the code hard to test and to reuse.
 7. Match each pattern or abstraction the change introduces to a problem the code has today. One built for a case nobody has asked for is speculative.
@@ -60,7 +74,7 @@ Walk the design axis in this order, and skip a step the change gives nothing to
 Three scope checks follow the walk:
 
 - When a change carries two concerns that could land as two changes, name the split. Size is no finding on its own, since one concern can run long.
-- On a refactor, count the concepts a reader must hold before and after. Complexity moved into a new file or function is moved, not reduced, so report it as such rather than as a design gain.
+- On a refactor, count the concepts a reader must hold before and after. Complexity moved into a new file or function is moved, not reduced, so never report it as a design gain.
 - Before calling removed code dead, state why it existed. Read `git blame` and the commit that added it, since a guard nobody remembers is often still guarding something.
 
 ## Hold every finding to the evidence bar
@@ -91,6 +105,8 @@ Three scope checks follow the walk:
 
 ### Claims and axes
 
+These flags fire on a claim accepted without its evidence.
+
 - You are calling code dead without having read the commit that added it.
 - A performance claim rests on a number you cannot trace to a repeated measurement.
 - An axis condition held and you moved past it without reading the reference it names.