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.