docs: add PR review steering guide#212
Conversation
Codify the review style from PR openabdev#210 as team standard: - 🔴🟡🟢 severity levels - Each comment: what/where/why/fix - Self-review checklist for authors - Review etiquette guidelines Credit to @the3mi for the review format.
When reviewing a PR, always consider: 1. What problem does it solve? 2. How does it solve it? 3. Were alternatives considered? 4. Is this the best approach?
the3mi
left a comment
There was a problem hiding this comment.
PR Review: docs/steering/pr-review.md
Overall: 🟢 Suggest Merge — solid contribution, two optional improvements noted below.
🟡 Minor: Zero-width space in code fence (line ~52)
The example block has a U+200B zero-width space before the backticks:
```rust
This may render fine on GitHub but can break in other Markdown renderers (GitBook, Notion, etc.). Just remove the invisible character so it is a clean ```rust.
🟡 Minor: Framework Q3 may not be actionable for AI agents
- What alternatives were considered — find rejected alternatives from PR description, discussion, or commit history...
As an AI reviewer, I typically only have the PR own context. Without explicit mention in the PR description, I cannot discover rejected alternatives from commit history.
Suggested tweak: reframe as an author-facing responsibility — "Did the author explain why this approach was chosen over alternatives in the PR description?" This puts the burden on the PR author rather than the reviewer.
🟢 Info: Everything else looks great
The severity levels (🔴🟡🟢), the four-question framework, and the self-review checklist are all clear and actionable. Good work codifying the team review culture!
Background
During PR #210, @the3mi demonstrated an excellent review style using severity levels (🔴🟡🟢) with concrete fix suggestions. This was effective enough that we want to codify it as a team standard.
What's added
docs/steering/pr-review.md— covers:Example
Uses the actual aspect ratio bug from PR #210 as the reference example.
Credit to @the3mi for the review format 🦞