Code Review Communication

This skill provides frameworks for effective code review communication - both giving feedback that lands well and receiving feedback without defensiveness.

When to Use This Skill

Writing a code review comment and want it to be clear and constructive
Receiving feedback that feels harsh and need perspective
Want to distinguish between blocking issues and minor suggestions
Need to communicate code quality concerns without damaging relationships
Preparing to review a junior developer's first PR

Core Frameworks

Conventional Comments

A labeling system that makes the intent of each comment crystal clear.

Format: [label] (decoration): explanation

Labels:

| Label | Meaning | Action Required | | ----- | ------- | --------------- | | praise | Highlight good work | None - encouragement | | nitpick | Minor style/preference issue | Optional | | suggestion | Improvement idea | Consider but not required | | issue | Must be addressed | Required before merge | | question | Need clarification | Response required | | thought | Sharing perspective | None - FYI only |

Decorations:

(non-blocking) - Explicitly optional
(blocking) - Must be resolved
(if-minor) - Only if the fix is trivial

Examples:

praise: This error handling is really thorough - I like how you covered the edge cases.

nitpick (non-blocking): Consider using a more descriptive variable name than `x`.

suggestion: You could use `Object.entries()` here for cleaner iteration.

issue (blocking): This SQL query is vulnerable to injection. Use parameterized queries.

question: What's the expected behavior if the user cancels mid-operation?

thought: I've seen this pattern cause issues with concurrent requests in the past.

Full reference: references/conventional-comments.md

Summary-Analysis-Suggestion Method

For larger reviews or when multiple comments are needed:

Summary - Start with what works (genuine positives)
Analysis - Identify specific areas needing attention
Suggestion - End with actionable recommendations

This prevents the "wall of criticism" effect that makes authors defensive.

Separating Code from Coder

The most important principle: criticize code, not people.

| Instead of... | Say... | | ------------- | ------ | | "You wrote this wrong" | "This function could be simplified" | | "You didn't think about X" | "There's an edge case here around X" | | "Why did you do it this way?" | "What's the reasoning behind this approach?" | | "You should know better" | "This is a common gotcha - here's the pattern" |

Use collaborative "we" language:

"We should add a test for this"
"How should we handle the null case?"
"Let's think about the performance implications"

Blocking vs Non-Blocking

Blocking issues (must fix):

Security vulnerabilities
Bugs that will cause production issues
Breaking changes to public APIs
Missing required tests for critical paths

Non-blocking issues (nice to have):

Style preferences
Alternative implementations
Minor optimizations
Documentation improvements

Rule of thumb: If you'd be comfortable if the author ignored this comment, it's non-blocking.

Receiving Feedback

Receiving code review feedback well is equally important. See references/receiving-feedback.md for:

Assuming good intent
Separating ego from code
Asking clarifying questions
Handling disagreements professionally
When to take discussions offline

Related Resources

references/conventional-comments.md - Full label taxonomy with examples
references/receiving-feedback.md - Guide to receiving feedback gracefully
feedback-conversations skill - For broader feedback (not just code)
/soft-skills:review-comment command - Generate a well-structured review comment

Version History

v1.0.0 (2025-12-26): Initial release

Last Updated

Date: 2025-12-26 Model: claude-opus-4-5-20251101