Labels for Clear Feedback in Peer Review
Conventional Comments provides a framework for offering clear and actionable feedback in peer review
Today I learned about Conventional Comments (conventionalcomments.org) from this Bluesky post from Andrew Heiss.
In my new role here at the UVA School of Data Science, I’ve been championing a more robust internal peer review framework, something I picked up while working serving on many proposal “red teams” during my tenure in consulting.
Whether it’s internal feedback on a draft proposal or external reviews on a manuscript, you’ve probably opened up a review and thought, “What exactly do they want me to change?” Peer review is full of vague comments like “unclear,” “please revise,” or “this needs work,” with very little signal about priority, intent, or next steps.
The Conventional Comments framework provides a more thoughtful framework. It borrows from software engineering code review and applies it to any kind of review: manuscripts, grants, student work, or internal drafts.
At its core, the idea is:
label [decorations]: subject
discussion (optional)
label is what kind of comment you are leaving.
decorations add extra context like “blocking” or “non-blocking.”
subject is the one line headline of your comment.
discussion is where you explain why and suggest what to do.
Because every comment starts with a label, both tone and intent become much clearer, and authors can quickly triage what to respond to first.
Here’s an example. See conventionalcomments.org for more.
