tomevault-io PR Review Conventions
Quick Start
Severity Levels
| Severity | Description | Blocking |
|---|---|---|
major |
Must be addressed before merging to production | Yes |
minor |
Non-blocking if merged, but should be addressed in follow-up | No |
suggestion |
Loose opinion — an idea the author can freely ignore | No |
nit |
Strong but unimportant opinion — stylistic preference | No |
Feedback Types
| Type | Description | Guidelines |
|---|---|---|
question |
Needs clarification from author | Use when intent is unclear or design decision needs explanation |
praise |
Pattern or technique deserving appreciation | Include only 2-3 per review — highlight genuinely impressive work |
Nit vs Suggestion
- Nit: "I feel strongly about this, but it doesn't really matter" (naming, formatting preferences)
- Suggestion: "Here's an idea you could consider" (alternative approach, optional optimization)
Review Language
- Use "we", "I", or "the code" instead of "you"
- Be specific in suggestions — include file paths and line numbers
- Provide actionable feedback with code examples when possible
- Prioritize: major items first, nits last
Praise Budget
Reviews should have 2-3 praise items maximum. Recognize genuinely impressive patterns, elegant solutions, or good architectural decisions. Don't overuse.
Review Checklist
Before finalizing any review, verify coverage of:
- Code correctness and logic
- Error handling
- Type safety
- Security implications
- Performance considerations
- Test coverage
- Documentation needs
- Conventional commit compliance
Verdict Criteria
| Condition | Verdict |
|---|---|
| Any major issues remain | CHANGES REQUESTED |
| Unanswered questions remain | NEEDS DISCUSSION |
| Only minor/suggestion/nit | APPROVED (with suggestions) |
| All items addressed or only praise | APPROVED |
Additional Resources
- For full review process, report template, and examples, see conventions.md
- For the complete review command, see
.cursor/commands/code-review/review-pr.md - For interactive review refinement, see
.cursor/commands/code-review/interactive-review.md
Converted and distributed by TomeVault — claim your Tome and manage your conversions.