diff --git a/.claude/skills/pre-review/SKILL.md b/.claude/skills/pre-review/SKILL.md index 33efd93d1e..df9a5a932d 100644 --- a/.claude/skills/pre-review/SKILL.md +++ b/.claude/skills/pre-review/SKILL.md @@ -33,24 +33,41 @@ after a clean review is instant. The push gate (below) checks that cache. The report is printed and kept in `~/.cache/prereview/.md`; `--status` shows the verdict of HEAD. - **Verify every finding** against the code at HEAD: open the lines and walk the sequence it describes. Drop a - finding the code does not support, and say why. Keep one even if it looks unlikely. + finding the code does not support, and say why. Keep one even if it looks unlikely. **Never lower a severity**: + the bot's verifier is this model, and on #1645/#1654/#1666 four of its six blockers were findings our reports + carried as suggestions, two of them downgraded from the model's own blocking. A finding is dropped only on + evidence: a test its sequence cannot make pass, or the bytecode of the dependency the module *resolves* — which + is neither the version `build.gradle` declares nor the newest jar in the Gradle cache. Ask Gradle, per module and + variant configuration (an Android module has no default `compileClasspath`): + `./gradlew ::dependencyInsight --configuration RuntimeClasspath --dependency `, + e.g. `./gradlew :wallet:dependencyInsight --configuration _testNet3DebugRuntimeClasspath --dependency + androidx.paging:paging-common`; then `javap` on that jar, resolved version noted. On #1666 both sides argued + from a file (`build.gradle` says 3.1.1; a 3.3.2 jar sat in the cache) and the command answers 3.3.2 — Room 2.7.1 + lifts the whole `androidx.paging` atomic group. An argument is not evidence. - **Fix the class, not the line.** Name the rule each finding breaks, then `git grep` every other place it must hold: callers, legacy / resume / retry / restore / background paths, the other screen that shows the same value. A sibling the review did not name is the next round's finding. - **Prefer narrowing or reverting to adding a mechanism.** A new cap, latch, mutex or persistence layer is - reviewed again at funds-safety depth. + reviewed again at funds-safety depth. A fix that needs a new field, flag, captured value or latch is a design + decision, not a fix round: write the alternative down and ask the user to take it to the maintainer on the PR + before coding it (#1653: one cache, four rounds, a count → an id set → a v3 fingerprint → a v4 digest; #1654: + "two decimals" → 21 commits, one mechanism per round; the maintainer's stated design was the one that held). - **Suggestions and nitpicks count.** Any open one withholds the bot's approval, and most are cheap. - Show the user a table (severity · file:line · finding · verified? · fix) before you change code, and follow the repository's conventions (CLAUDE.md, `.claude/agents/DEVELOPMENT-PATTERNS.md`). -- After the fixes, commit and run the review again. The new commit is a new range. **At most two rounds per - push.** A fix adds code, and the next round reads that code with the same eyes: on a long-running change the +- After the fixes, commit and run the review again. The new commit is a new range, and this second round is not + optional once the first found a blocker: on #1670 round 1 found three blockers, the fix went out unreviewed, and + the bot's first blocker sat on a line of that fix commit (`ConnectAvailability.kt`, `1d216ed3e`). **At most two + rounds per push.** A fix adds code, and the next round reads that code with the same eyes: on a long-running change the rounds stop converging (this skill's own branch took 9 rounds on one of the bot's findings, each round a real but smaller hole in the previous fix). After the second round, push what is there and let thepastaclaw be the judge — its round is cheaper than ours, it runs four passes, and it carries findings forward anyway. Say in the PR what the last round still listed. - A pre-existing problem the change neither introduced nor is responsible for is not a finding: the bot leaves those out too, so drop it. A finding that IS in scope but that the user decides to defer needs a tracking issue - linked on the PR, or the bot keeps reporting it. Draft that issue for the user; do not open it yourself. + linked on the PR, or the bot keeps reporting it — an "open items" list in the PR description is not a deferral + (#1662: four of the bot's eight blockers were the items the description had listed as known and not addressed). + Draft that issue for the user; do not open it yourself. ## Scope @@ -69,13 +86,17 @@ login) is in scope and gets fixed. path it affects — then either fix that path or argue the point, on the thread.) 2. **At most two local rounds per push** (a third only when the user asks for it). When each round finds holes in the previous fix, get out with the smallest change, or ask the user what to do next. -3. **Locally, blocking and major only.** Suggestions and nitpicks wait for the bot's own round, where they are - cheap to close and where its approval needs them closed. +3. **Locally, every blocking finding and every suggestion that is a few lines of existing code.** The bot approves + only at zero findings of every severity, and its verifier upgrades about half of what this report calls a + suggestion (4 of 6 blockers on #1645/#1654/#1666 were our suggestions). A larger suggestion is deferred with a + tracking issue linked on the PR, in the same push. Nitpicks wait for the bot's own round. 4. **Push back when a comment is not about our code or does not matter in our case**: reply with the reasons, do not resolve the thread — the bot re-checks on reply. 5. **The narrowest fix, never a new mechanism for a suggestion.** Fix a bot's suggestion only when it is a line or two of the existing code; otherwise answer it and defer. On this skill's own PR, two of the three blockers of a round came from the previous round's suggestion fixes. +6. **A new mechanism is a design decision.** A fix that needs a new field, flag, captured value or latch stops here: + the alternative goes to the user, and to the maintainer on the PR, before anyone codes it (see "Act on it"). Pushing is the user's call. Push only when asked. diff --git a/docs/code-knowledge/09-review-bots.md b/docs/code-knowledge/09-review-bots.md index 642c9d19f5..c4d9328470 100644 --- a/docs/code-knowledge/09-review-bots.md +++ b/docs/code-knowledge/09-review-bots.md @@ -34,8 +34,17 @@ 1. Fix only code the PR touches. A finding on code outside the PR gets an answer explaining why it is not this change's concern; it is not silently fixed. 2. At most two local `/pre-review` rounds per push. A third only when the owner asks for it. If we are digging in (each round finds holes in the previous fix), - get out with the smallest change or ask. -3. Locally, act only on blocking/major findings. Suggestions and nitpicks wait for the bot's own round. + get out with the smallest change or ask. The second round is not optional once the first found a blocker: the fix + is new code the bot reads with the same eyes. On #1670 round 1 found three blockers, the fix went out unreviewed, + and the bot's first blocker sat on a line of that fix commit (`ConnectAvailability.kt`, `1d216ed3e`). + A pre-review finding deferred in the PR description is not deferred for the bot: on #1662 four of its eight + blockers were the "open items (known, not addressed here)" the description listed. Deferring needs a tracking + issue linked on the PR, or the item gets fixed. +3. Locally, fix every blocking finding and every suggestion the GPT-6.1 Sol lane raised that is a few lines of + existing code. The bot approves only at zero findings of every severity, and its verifier does not share our + severity scale: on #1645, #1654 and #1666 (2026-10-27 … 11-03) four of its six blockers were suggestions in our + own pre-review report, twice after we had downgraded what the Sol lane rated blocking. A larger suggestion is + deferred with a tracking issue linked on the PR, in the same push. Nitpicks wait for the bot's own round. 4. Pushing back on thepastaclaw is allowed and expected when a comment does not concern our code or is immaterial in our case. 5. Fix only what the bot found, the narrowest way, with no new mechanism. A suggestion is fixed only when it is a line @@ -43,13 +52,29 @@ findings forward. 6. Once the bot reports no blocking findings, stop fixing. Report the remaining suggestions and nitpicks; take a new blocker to the owner first. +7. A fix that needs a new field, flag, capture or latch is a design decision, not a fix round. Write the alternative + down and ask the maintainer on the PR before coding it; prefer the design the maintainer stated from the first + commit. Four of the six blockers on #1645/#1654/#1666 sat on code an earlier fix round wrote, and #1654 went from + "round the fiat line to two decimals" to 21 commits one mechanism at a time (`maxSelected` → `pinnedAmount` → a + captured amount → validating the captured amount); the maintainer's `maxSelected` design was the one that held. +8. A refutation cites the version the module *resolves*, which is neither the one `build.gradle` declares nor the + newest jar in the Gradle cache. Ask Gradle, per module and variant configuration (an Android module has no + default `compileClasspath`): + `./gradlew ::dependencyInsight --configuration RuntimeClasspath --dependency `, + e.g. `./gradlew :wallet:dependencyInsight --configuration _testNet3DebugRuntimeClasspath --dependency + androidx.paging:paging-common`. Then `javap` on that jar, and the resolved version in the reply. On #1666 both + sides argued from a file: `wallet/build.gradle` says `paging-runtime-ktx:3.1.1`, so one side reasoned from 3.1.1 + (whose `PagingData.empty()` dispatches load states) and the other from the 3.3.2 jar it found in the cache. The + command above answers `3.3.2`: Room 2.7.1, pinned through the SDK, lifts the whole `androidx.paging` atomic + group by conflict resolution. A failing test the finding's sequence cannot make pass is the other acceptable + evidence. An argument is not. ## Pushback that works | Situation | What to say (with evidence) | Example | |---|---|---| | The defect exists unchanged in the base | Name the base commit; say it is not introduced by the diff; link a tracking issue | #1616 → #1626, #1576, #1575, #1571 | | The proper fix needs the SDK | Name the missing primitive, say why every app-side heuristic leaves a gap, link an issue | #1621 → dash-wallet#1635; #1607 `broadcastRawTransaction` | -| Behaviour is already correct | Show the current code or the library (e.g. `javap` shows both exceptions extend `CompletionException`) | #1608, #1566 | +| Behaviour is already correct | Show the current code or the library (e.g. `javap` shows both exceptions extend `CompletionException`) — from the jar `dependencyInsight` resolves for the module, with its version | #1608, #1566; the wrong jar on #1666 | | Not reachable | Name the production gate that makes it unreachable | #1607 `shouldPrompt()` | | Recovery already exists | Name the code path that recovers (`MainActivity.onResume()` restarts the service) | #1568 | | Inherited mechanism handles it | E.g. `BaseConfig` clears all keys on wallet wipe | #1595 |