Every comment in the review looks equally urgent.
Formatting notes sit beside broken code examples.
The team spends 30 minutes debating comma placement while critical bugs slip through.
To fix this, I introduced a tagging system for review comments.
I see this pattern in docs reviews: reviewers leave comments without indicating priority.
Contributors treat every comment as blocking.
The breakdown happens in three ways:
Contributors waste time on non-issues: Someone suggests “maybe use a bullet list here instead of numbered?” The contributor spends an hour reformatting. Turns out it was just a passing thought.
Critical issues get missed: Seventeen comments deep, one mentions the API endpoint is wrong. The PR merges. Users hit a broken example. Support tickets pile up.
Review cycles multiply: Contributor fixes what they think matters. Reviewer expected different fixes. Another round. The two-day PR becomes a two-week ordeal.
The root cause: no shared language for priority.
The fix: a two-part tag for every review comment: severity + category.
Severity
Severity tells contributors the importance of the fix.
blocker: Must fix before merge. Breaks functionality or blocks critical understanding.
improvement: Should fix before publication. Improves clarity, structure, or usability.
optional: Personal preferences, stylistic suggestions, future ideas.
Category
Categories tell contributors more context about what kind of fix to make at first glance.
clarity: Confusing or incomplete explanations.
bug Incorrect code, wrong output, factual errors.
organization: Issues with flow, structure, content order.
style: Wording, formatting, tone.
consistency: Conflicts with other sections, terminology, or examples.
Add others if your team needs them. Keep the list short.
(improvement, clarity): Step 3 assumes readers know what environment variables are. Add a one-line explanation or link to prerequisites.
(blocker, bug): This code example throws an error. Missing import statement at the top.
(improvement, organization): Move the troubleshooting section before advanced configuration. Users hit errors at the basic level first.
(optional, clarity): This explanation works, but the second paragraph repeats the first. Consider cutting it.
Contributors know what to fix immediately. Scan for blocker tags. Fix those first. Everything else waits.
Contributors feel less overwhelmed: Seventeen comments looks terrifying. Two blockers, eight improvements, seven optional? Manageable.
Debates end faster: No more “should we merge this or wait?” If there are no blockers, merge. Track improvements for follow-up.
Review culture improves: New reviewers see the pattern. They start tagging their comments. The team develops shared expectations.
Tagging doesn’t fix slow reviewers: If your team takes three days to look at PRs, tags won’t help. That’s a process problem.
Tagging doesn’t fix bad feedback: “(blocker, style): I don’t like this wording” is still bad feedback. Add context. Explain why.
Tagging doesn’t replace good judgment. A reviewer still needs to know what’s actually a blocker vs. a preference.
Don’t overthink it. Start tagging your review comments this week.
Put the tag at the start of each comment. Make it visible.
Within two weeks, you’ll see fewer debates about what blocks merge. Contributors will know what to fix first. Reviews will move faster. Others will copy you.
The system works because it forces one decision upfront: is this blocking or not?
Make that decision explicit. Stop wasting time guessing.