From 6d7dab2f34811b858f9a20c136348ee129f992a7 Mon Sep 17 00:00:00 2001 From: Gavin Lucas Date: Tue, 6 Oct 2026 13:20:16 +0100 Subject: [PATCH] Have the review raise recorded state in docs and comments Documentation and comments kept gaining claims about how things are now - counts, measured figures, what was tested, "currently", settings held elsewhere - which go stale as soon as anything changes and are then worse than nothing. The instruction files already forbid them, but a review that checks each claim against the code passes one that is true on the day, so they were approved round after round. The prompt now asks every review to check what the change adds to docs and comments for recorded state, raise each instance as a maintainability finding even when it is true today, and say where the fact already lives instead. Rules, behaviour that tests hold, and accepted limitations are excluded. The README says so. Signed-off-by: Gavin Lucas --- .github/workflows/claude-review.yaml | 12 ++++++++++++ README.md | 6 ++++++ 2 files changed, 18 insertions(+) diff --git a/.github/workflows/claude-review.yaml b/.github/workflows/claude-review.yaml index 645cdd5..3bd5677 100644 --- a/.github/workflows/claude-review.yaml +++ b/.github/workflows/claude-review.yaml @@ -306,6 +306,18 @@ jobs: assert the wrong thing, and at documentation the change makes untrue. The aim is that a later round finds only problems in later fixes, not problems that were here now. + Check every line the change adds or edits in documentation, code comments, workflow + comments and instruction files for recorded state: a claim about how things are now + that the system can already answer, or that will become untrue when something else + changes. Examples: counts and sizes ("1150 files", "94 kinds"); figures measured on a + particular day; what was tested, shown to fail or checked when something was done; + "currently", "today", "for now", "not yet", "until X lands"; descriptions of settings, + accounts or configuration held somewhere else. Raise each as a maintainability + finding even when it is true today, and say where the fact already lives - the + command, test or file that answers it, or the commit message or pull request, where a + record of what was done belongs. Not findings: rules and the reasons for them, + behaviour that code or tests hold true, and accepted limitations stated as limitations. + For a delta review: the earlier commits have been reviewed. Review what changed in the range, including how it interacts with the code around it, which you should read. Structure the review under these four headings, in this order, so a reader does not diff --git a/README.md b/README.md index 6ec9749..7387a46 100644 --- a/README.md +++ b/README.md @@ -63,6 +63,12 @@ inputs are at the top of `.github/workflows/claude-review.yaml`. read for it. A force-push that drops that commit from the branch falls back to a full review. A request by comment for a commit already reviewed is answered without running one; a push of one only says so in the log, because nobody asked. +- **Recorded state.** Every review checks what the change adds to documentation and comments + for claims about how things are now - counts, measured figures, what was tested, "currently" + or "until X lands", settings held elsewhere - and raises each, even when true on the day, + saying where the fact already lives. Such claims go stale as soon as something changes and are + then worse than nothing; a record of what was done belongs in the commit message or pull + request. - **What Claude can do.** Read the checkout and run `git diff`, `git log` and `git show`. It returns a verdict, approve or changes requested, and a review body as structured output, and a later step posts them, so the session never holds a token that can write to GitHub.