Skip to content

docs: align code-review README with the current validation-based command - #79150

Open
Codeturion wants to merge 2 commits into
anthropics:mainfrom
Codeturion:fix-code-review-readme
Open

docs: align code-review README with the current validation-based command#79150
Codeturion wants to merge 2 commits into
anthropics:mainfrom
Codeturion:fix-code-review-readme

Conversation

@Codeturion

@Codeturion Codeturion commented Jul 19, 2026 •
edited
Loading

Copy link
Copy Markdown

Summary

The code-review README describes a pipeline the command no longer implements: a git blame/history agent, a 0-100 confidence scoring system with an 80 threshold, and a Configuration section telling users to edit a "Filter out any issues with a score less than 80." line that does not exist in commands/code-review.md. The command actually runs 2 CLAUDE.md compliance agents plus 2 bug agents and validates each candidate issue with a dedicated subagent. This PR rewrites the drifted sections to match, and removes the dead Configuration subsection.

A second commit fixes the --comment half of the README, per @kraigparkinson's review below. The "Review comment format" block showed a single numbered summary comment. Step 9 stopped posting that in 9fd556d9 and now posts one inline comment per issue, so the documented format was the one output the command never produces. The "No review comment posted" cause list also omitted the commonest cause: e4f68203 made terminal-only the default, so a run without --comment posts nothing.

Files changed

  • plugins/code-review/README.md (tagline, Overview, step list, example, Features, scoring block removed, Best Practices, Troubleshooting, Tips, Configuration, Technical Details; then the --comment output description, the "No review comment posted" causes, and the gh integration list)

Verification

Setup: fresh checkout of main; grep-based consistency check between README and commands/code-review.md before and after. The second commit adds a runnable script, verify.sh <plugins/code-review dir>, which asserts four facts about the command file and two about the README. Pointed at a tree built from upstream/main, the two README checks fail; pointed at this branch, all six pass.

Details: for each removed concept, confirmed zero occurrences in the command file; for each replacement, confirmed the command file actually specifies it (steps 4-6: two Opus bug agents, validation subagents, filter unvalidated). The one remaining use of "confidence" in the README ("confirmed with high confidence") mirrors the command's own step-5 wording. For the second commit: the command file has exactly one gh pr comment call site outside allowed-tools, and it is the --comment + no-issues path (step 7); the --comment + issues path goes through mcp__github_inline_comment__create_inline_comment (step 9); step 7 stops before any GitHub write when --comment is absent.

Comparisons

Term README before README after Command file
"score less than 80" 1 0 0
"git blame" / history analyzer 4 0 0
confidence scoring / threshold 12 0 0
validation subagents 0 described steps 5-6
multi-issue ## Code review summary example 1 0 0 (removed in 9fd556d9)
missing --comment as a no-comment cause 0 1 step 7, default since e4f68203
gh described as posting inline comments 1 0 inline comments use the MCP tool

Refs

Fixes #79145

@github-actions github-actions Bot mentioned this pull request Jul 20, 2026
Open
@hulincup hulincup mentioned this pull request Jul 31, 2026
Open
4 of 5 tasks
@Codeturion Codeturion mentioned this pull request Aug 17, 2026
Closed
@kraigparkinson

kraigparkinson commented Sep 3, 2026

Copy link
Copy Markdown

Two drifted spots survive this diff, both in the --comment half of the README — which is
the half a reader consults precisely when the plugin is silent.

1. **Review comment format:** (README lines 59–76) documents a comment the command no
longer posts.

The example shows a single ## Code review summary listing three numbered issues. Since
9fd556d9 ("Skip summary comment when posting inline comments"), step 9 posts one inline
comment per issue via mcp__github_inline_comment__create_inline_comment. The only
gh pr comment left in the command is step 7's no-issues case, whose format the command
pins in its own Notes block:

## Code review

No issues found. Checked for bugs and CLAUDE.md compliance.

So the format currently documented is the one case the command never produces.

2. The "No review comment posted" cause list omits the most likely cause.

Since e4f68203 made no-comment the default, the commonest reason for /code-review running
and no comment appearing is that --comment was not passed. The list names four skip
conditions, and after this PR the no-issues case, but never that one.

We hit exactly this: a CI workflow invoking /code-review without --comment — green check,
permanent silence — and this list is where we looked first.

Suggested bullet, ahead of the others:

- `--comment` was not passed (terminal output only is the default)

Happy to open a follow-up PR for either if you would rather keep this diff scoped. Note that
(1) is conflict-free with your hunks; (2) lands inside the block your @@ -176,7 hunk already
edits, so it is probably cleanest here.

This was referenced Sep 3, 2026
Open
Closed
@github-actions github-actions Bot mentioned this pull request Sep 4, 2026
Open
@Codeturion
docs: correct where /code-review posts its review
f093220 
The --comment half of the README still described the pre-9fd556d9 behaviour.
The Review comment format block showed a single numbered summary comment,
which step 9 stopped posting when it moved to one inline comment per issue.
The only gh pr comment left is the no-issues case.

The No review comment posted cause list also omitted the commonest cause.
e4f6820 made terminal-only output the default, so a run without --comment
posts nothing at all.
@Codeturion

Codeturion commented Sep 23, 2026

Copy link
Copy Markdown
Author

Both confirmed against commands/code-review.md on main, and both are now in the diff (f093220).

1. Replaced the **Review comment format:** block with a "Where the review goes" section that
covers the three real outcomes: no --comment means terminal only, --comment with validated
issues means one inline comment per issue, --comment with nothing surviving validation means the
single ## Code review / No issues found. comment pinned in the command's Notes block. The command
file has exactly one gh pr comment site outside allowed-tools and it is that no-issues path, so
the old numbered-summary example was documenting output the command cannot produce.

2. Added your bullet at the top of the cause list, verbatim. Agreed it belongs ahead of the
skip conditions.

One more in the same family while I was in there: the GitHub integration list credited gh with
"Posting review comments". Inline comments go through mcp__github_inline_comment__create_inline_comment,
so gh now reads as posting the no-issues summary comment, with a line noting where inline comments
actually come from.

Verification is a script this time rather than a table:
notes/repro-code-review-readme/verify.sh <plugins/code-review dir> asserts four facts about the
command file and two about the README. Against a tree built from upstream/main the two README
checks fail; against this branch all six pass.

Thanks for the review, and for the CI report. A green check with permanent silence is exactly the
failure mode that cause list should have caught.

This was referenced Sep 23, 2026
Open
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

code-review README documents a git blame agent and 0-100 confidence scoring that no longer exist in the command

2 participants

@Codeturion @kraigparkinson