Kind code review
Two modes. Pick the one that matches the request.
Labels
Every comment starts with exactly one:
blocker:a bug, security hole, data loss, broken contract, or anything you'd hold the merge forsuggestion:a better approach, with a reason. The author can declinequestion:you don't understand something yet, or you suspect a problem but aren't surenit:style, naming, typos, formattingpraise:something done well, and why it's good
If you're unsure whether something is a bug, it's a question:, not a blocker:.
How every comment is written
- What you see. Name the exact line, function or value.
- Why it matters. The cost, the risk, or the input that breaks it. Concrete, not "this is bad practice".
- A way forward. A specific change (a short code snippet if it helps), or a real question.
Wording rules:
- Talk about the code, not the person. "This function returns null when..." instead of "You forgot...". "We" and "this" are fine.
- No "just", "obviously", "simply", "why didn't you", "did you even". No sarcasm, no "??".
- Keep it short. One to three sentences is usually enough.
- Don't invent facts. If you haven't checked how a function behaves, ask instead of asserting.
- Offer a follow-up PR for big refactors that aren't needed for this change.
Mode 1: review a PR or diff
- Read the whole change first, plus the files around it that you need to understand it. Find out what the PR is trying to do from its title, description or commits.
- Write inline comments using the format above, each tied to a file and line.
- Group all
nit:items into one comment (or one section) instead of scattering them, unless the user wants them inline. - Add at least one
praise:when something really deserves it. Make it specific: what's good and why. Don't invent praise for an empty or weak change. - End with a summary in this order:
## Summary
<one or two sentences on what the PR does and the overall state>
### Blockers (must fix before merge)
- file:line short description
### Suggestions and questions
- file:line short description
### Nits
- file:line short description
### What's good
- short description
Leave a section out if it's empty. If there are no blockers, say so plainly: "No blockers."
- Don't post anything to GitHub, GitLab or any other service unless the user asks for it.
Mode 2: rewrite my review comments
Triggered by "rewrite my review comments", "make these nicer", "soften this" or a pasted list of draft comments.
- Keep the reviewer's meaning and severity. If the draft says a thing is broken, the rewrite still says it's broken. Kind doesn't mean vague.
- Pick a label for each one. If the draft doesn't say enough to tell a bug from a preference, choose the lighter label and say so.
- Rewrite each one into the three-part shape. If the draft has no reason or no suggestion and the code isn't available, ask the user for the missing piece, or put a short bracketed placeholder like
[what breaks?]and point it out. - Return them as a list, original then rewrite:
1. Original: this is wrong
Rewrite: blocker: this runs the query inside the loop, so 200 items make 200 calls. Could we fetch them in one query before the loop?
- If several drafts are small nits, offer to merge them into one grouped comment.
Phrases to reach for
See PHRASES.md in this skill's folder for a table of "instead of this, try this".