Conventional Comments
conventional-comments
Write structured code review comments using Conventional Comments format. Use when reviewing PRs, writing code review feedback, or asked to "comment on this code" or "review this PR".
SKILL.md
Full skill instructions
Conventional Comments
Write code review comments in Conventional Comments format (https://conventionalcomments.org).
Format
<label>[!] [(decorations)]: <subject>
[discussion]
| Part | Required | Description |
|---|---|---|
label | Yes | Comment type (see Labels below) |
! | No | Blocking indicator—must resolve before approval |
(decoration) | No | Comma-separated context tags (e.g., (security)) |
subject | Yes | Main message (1 line) |
discussion | No | Additional reasoning or suggested fix (1-3 lines) |
Labels
| Label | Description |
|---|---|
issue | Identifies a problem that needs to be addressed. |
suggestion | Proposes an improvement with an explicit change. |
todo | Small, necessary change. Less severe than an issue. |
question | Seeks clarification or investigation. |
note | Information for the reader. Does not require action. |
typo | Points out a typographical error. |
Do NOT use: praise, nitpick, quibble — focus on actionable feedback only.
Decorations
| Decoration | Use when |
|---|---|
(security) | Comment relates to security vulnerabilities. |
(performance) | Comment relates to performance impact. |
(a11y) | Comment relates to accessibility. |
(ux) | Comment relates to user experience. |
Examples
Basic suggestion
suggestion: Consider using optional chaining here.
`user && user.profile && user.profile.name` can be simplified to `user?.profile?.name`.
Blocking issue
issue!: This function silently swallows exceptions.
Either log the error or propagate it to the caller.
With security decoration
suggestion! (security): User input should not be directly embedded in SQL.
Use prepared statements to prevent SQL injection.
With performance decoration
issue (performance): This query runs inside a loop causing N+1 problem.
Batch the IDs and fetch all records in a single query.
Simple todo
todo: Add null check before accessing `user.email`.
Question
question: Is this timeout value intentional?
300ms seems short for API calls that may span regions.
Note (informational)
note: This pattern is also used in `auth-service.ts:45`.