code-review-communication

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:

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:

1. Summary - Start with what works (genuine positives)
2. Analysis - Identify specific areas needing attention
3. 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.

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