tomevault-io 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 examplesreferences/receiving-feedback.md- Guide to receiving feedback gracefullyfeedback-conversationsskill - For broader feedback (not just code)/soft-skills:review-commentcommand - 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
Converted and distributed by TomeVault — claim your Tome and manage your conversions.