Skip to content

Have the review raise recorded state in docs and comments - #10

Merged
GavinLucas merged 1 commit into
mainfrom
review-recorded-state
Oct 6, 2026
Merged

GavinLucas merged 1 commit into
mainfrom
review-recorded-state

Conversation

@GavinLucas

Copy link
Copy Markdown
Contributor

Documentation and comments keep gaining claims about how things are now: counts, measured figures, what was tested, "currently", and settings held elsewhere. They go stale as soon as anything changes. The callers' instruction files 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.

What changes

  • The prompt, in .github/workflows/claude-review.yaml, gains one paragraph for every review, full or delta. It asks the reviewer to:

    • check each line the change adds or edits in docs, code comments, workflow comments and instruction files for recorded state;
    • raise each instance as a maintainability finding, even when it is true today;
    • say where the fact already lives: the command, test or file that answers it, or the commit message or pull request for a record of what was done.

    Rules and their reasons, behaviour that tests hold, and accepted limitations are excluded.

  • The README's "The Claude review" section gains a bullet saying so.

Verification

  • The workflow YAML parses. The paragraph lands inside the prompt block, and the added lines are plain ASCII.
  • actionlint was not run locally. This repository's CI runs it.
  • Whether reviews actually raise recorded state shows only once one runs with this prompt. The first will be quaffed's pin-bump pull request: a pull request's own caller workflow decides which pinned version reviews it.

After merging

Tag v1.2.0, then bump the pin in each repository that calls this one.

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 <Gavin@L337.org>
@GavinLucas
GavinLucas merged commit 68eac35 into main Oct 6, 2026
5 checks passed
@GavinLucas
GavinLucas deleted the review-recorded-state branch October 6, 2026 12:22
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant