Repository navigation
Have the review raise recorded state in docs and comments - #10
Merged
Merged
Conversation
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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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: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
promptblock, and the added lines are plain ASCII.After merging
Tag
v1.2.0, then bump the pin in each repository that calls this one.