docs(contributing): make AI-review-comment handling an explicit convention#728
Conversation
…ntion The advisory AI review never blocks merge, so its comments can be silently inherited or ignored. Codify the team norm: before arming auto-merge, the author reads each AI comment and either addresses it in a follow-up commit or replies on the thread with the reason for deferring. A green/red review check says nothing about whether the comments were considered. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
|
Claude finished @blove's task in 32s —— View job Review
Docs-only change — looks good. The new paragraph fits naturally between the existing description of the advisory review workflow and the OSSF Scorecard note. A few observations: Clarity / wording The sentence "before arming auto-merge" ties the convention specifically to the auto-merge flow. That's accurate for the current setup but could silently exclude PRs that are merged manually without ever enabling auto-merge. Consider whether the intent is broader — e.g. "before merging (or arming auto-merge)" — so the norm applies regardless of how the merge is triggered. Completeness The paragraph describes what to do (address or reply with reason) but doesn't say where that response should live. Inline thread reply is implied, but a brief clarifying phrase like "replies on the thread" (already present) vs. "resolves the conversation" makes a difference if GitHub conversation-resolution is ever toggled on later. The current wording ("replies on the thread") is fine for now. No issues with correctness, security, or the |
1 participant
What
Codifies how we handle the advisory AI code review's comments, per a process decision: convention, not a gate.
The
claude-review.ymlreview is advisory — it never blocks merge — so its comments can be silently inherited or ignored (and a flaky redreviewcheck can even look like a blocker while enforcing nothing). This adds one paragraph to the existing Code-review section ofCONTRIBUTING.md:Why convention over enforcement
We explicitly chose the lowest-friction option (over required-conversation-resolution or making the review check required), because the review workflow has been flaky (
success → action_required → failureacross recent commits) and we don't want merges coupled to its reliability. The norm lives in docs; discipline applies it.Docs-only. No code or workflow changes.
🤖 Generated with Claude Code