| name | comment-format |
| description | Conventional Comments structure for review feedback. Labels, decorations and tone. Use when writing review comments, giving code feedback or posting PR review observations. Pairs with code-review-standard for what to evaluate. Follow the user's writing voice and prose style guides for comment text.
|
Conventional Comments
Format
<label> [decorations]: <subject>
[discussion]
Every review comment follows this structure. The label
classifies the intent, decorations indicate severity, the
subject is a one-line summary and the discussion is where
you explain your reasoning.
Labels
| Label | Purpose | Blocking? |
|---|
praise | Something positive | Never |
nitpick | Trivial preference | Never |
suggestion | Proposed improvement | Sometimes |
issue | Specific problem | Often |
question | Potential concern | Sometimes |
thought | Idea from reviewing | Never |
todo | Small necessary change | Usually |
note | Informational highlight | Never |
chore | Process requirement | Sometimes |
Label Selection
- Use
praise at least once per review; acknowledge
things done well.
- Pair
issue with suggestion when possible; don't
just point out problems, offer alternatives.
- Use
question when genuinely unsure, not as passive
aggression.
- Use
nitpick for pure preference; be honest about it.
- Use
thought for ideas that don't need action.
Decorations
Add parenthetical decorations after the label:
(blocking): must be resolved before merge.(non-blocking): won't prevent merge.(if-minor): resolve only if the fix is trivial.
Examples:
suggestion (non-blocking): Consider extracting validation...
issue (blocking): Missing null check causes crash...
nitpick (non-blocking): Prefer const over let here...
Tone
Canadian-Polite and Instructional
The tone should be warm, instructional and
teaching-oriented. Not just "what's wrong" but "what I
think and why." Explain your reasoning, suggest
alternatives and teach.
The structural format here (labels, decorations,
subject/discussion) is the container; the prose inside it
should follow the user's writing voice and prose style
guides so the comments sound like something they would
actually write.
Good Examples
suggestion (non-blocking): Consider using the existing
`validateInput()` helper here.
I noticed that `src/utils/validation.ts:23` already has a
validation function that handles this exact case. Using it
would keep the validation logic in one place and make it
easier to update if the rules change. The pattern used in
`src/api/users.ts:45` shows how other endpoints integrate
with it.
question (non-blocking): What happens if `prefs` is null
here?
I see the function accepts `prefs` without a null check,
but looking at the callers in `src/routes/settings.ts:30`,
it seems possible for the request body to be empty. The
existing pattern in `src/api/users.ts:12` guards against
this with an early return; it might be worth considering the
same approach here.
praise: Clean separation of concerns here.
The way validation, transformation and persistence are
handled in separate steps makes this very easy to follow
and test independently. Nice work.
Bad Examples
issue: Use validateInput() instead.
→ Terse and demanding. No explanation of why.
question: Did you not see the existing validation helper?
→ Passive-aggressive. Implies negligence.
suggestion: This is wrong, fix it.
→ Not a suggestion, and not helpful.
Evidence-Based Comments
Cite concrete evidence in your comments:
- Reference specific files and line numbers.
- Show search results (
rg output) for patterns.
- Link to existing implementations as examples.
- Quote relevant documentation or conventions.
Formatting in add-comment
When calling pr_review with add-comment, map the
conventional comment format to the tool's structured fields:
label: the conventional comment label.decorations: array of decorations, e.g. ["non-blocking"].subject: the subject line after the colon.discussion: the body paragraphs explaining reasoning.
The extension takes care of formatting these into the
conventional comment syntax when posting to GitHub.
What Not to Do
- Don't use labels as weapons ("issue: you did this wrong").
- Don't mark everything as blocking.
- Don't skip the discussion; the reasoning matters most.
- Don't forget praise; reviews are for encouragement too.
- Don't be vague in discussions ("this seems off").
- Don't use
question to make demands.
