conventional-comments

Scope

This skill defines the format of each review comment and recommended communication practices. It does not define:

• Review content. Substance, depth, and what's worth flagging come from the artifact and the user's request, not from this skill.
• Review structure. This skill formats individual comments; it doesn't organize them — pick the structure you find the most suitable.
• Review length. The number of comments must be as much or as little as the work warrants.

Format

Every comment follows this shape:

<label> [decorations]: <subject>

[discussion]

• label — a single lowercase English word signaling the kind of comment. Bold in Markdown (e.g. **suggestion:**).
• decorations (optional) — lowercase comma-separated qualifiers in parentheses, sitting between label and colon. Decorations classify comments that share a label. Example: **issue (ux,non-blocking):**.
• subject — the main message, on the same line as the label.
• discussion (optional) — supporting context, reasoning, examples, patches, or "why / next steps" notes. When a discussion is present, a blank line between the subject line and the discussion is required.

Labels

• Use one label per comment.
• Diverging from the following list is fine if a different label fits better.

Decorations

Decorations can be review-specific — (security), (ux), (test), (perf), (a11y) are common. Use them when they sharpen the comment. Keep the vocabulary of decorations small and unambiguous across the whole review. Keep per-comment decorations few; if a comment needs many, consider splitting it.

Communication practices

The standard's communication guide recommends:

Be curious

Don't assume full context. When unsure whether a problem is real, prefer question: over issue: or suggestion:.

Avoid:

**suggestion:** This bug could be solved in the `Main` component. Probably less code.

Prefer:

**question:** Could we solve this in the `Main` component?

It might be a simpler fix.

Leave actionable comments

Make it clear how to resolve the comment. If there's no obvious path forward, say so explicitly.

Combine similar comments

Don't fragment one concern across many tiny comments. Batch related issues into a single comment with a patch or example.

Avoid:

Ten separate **polish:** m_foo → foo comments.

Prefer:

**polish:** Rename all `m_X` variables to `X` — the `m_` prefix isn't used elsewhere in this project.

E.g. `m_foo` → `foo`, `m_bar` → `bar`, `m_quackaroo` → `quackaroo`.

Replace "you" with "we"

"You" places focus on the person; "we" focuses on the task.

Avoid:

**issue:** You should write tests for this.

Prefer:

**todo:** We should write tests for this.

Don't restate the label

The label signals the comment's type, stance, and that something is being said. Don't restate any of that — drop hedging, introductory phrases, fillers, and pleasantries.

Avoid:

**issue:** I think this might be a problem — looking at the code, the function basically swallows exceptions silently. Hope this helps!

Prefer:

**issue:** The function silently swallows exceptions.

Language behavior

• Labels and decorations are always in English — they're the canonical tokens of the standard and must not be translated.
• Subject and discussion match the language of the user's message — Russian message, Russian subject and discussion. Same for any other language.

Example (Russian content, English label):

**suggestion (non-blocking):** Стоит вынести валидацию в отдельную функцию.

Сейчас в обработчике смешаны валидация и сохранение — разделение упростит тестирование и переиспользование.