From 8cf2eab4532c76b0d1fa287fbf775d570621c673 Mon Sep 17 00:00:00 2001
From: chaodu-agent <chaodu-agent@users.noreply.github.com>
Date: Sat, 11 Apr 2026 11:30:10 +0000
Subject: [PATCH 1/2] docs: add PR review steering guide
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Codify the review style from PR #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.
---
 docs/steering/pr-review.md | 57 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 57 insertions(+)
 create mode 100644 docs/steering/pr-review.md

diff --git a/docs/steering/pr-review.md b/docs/steering/pr-review.md
new file mode 100644
index 00000000..662b2616
--- /dev/null
+++ b/docs/steering/pr-review.md
@@ -0,0 +1,57 @@
+# PR Review Guide for openabdev/openab
+
+## Severity Levels
+
+Use emoji + color to classify each review comment:
+
+| Level | Emoji | Meaning | Action Required |
+|-------|-------|---------|-----------------|
+| 🔴 Critical | `## 🔴 Critical:` | Correctness bug, security issue, data loss risk | Must fix before merge |
+| 🟡 Minor | `## 🟡 Minor:` | Style inconsistency, missing defense-in-depth, non-blocking improvement | Should fix, doesn't block merge |
+| 🟢 Info | `## 🟢 Info:` | Knowledge sharing, future consideration, design tradeoff note | No action needed |
+
+## Comment Format
+
+Each review comment should include:
+
+1. **What's wrong** — describe the issue clearly
+2. **Where** — file path and line number
+3. **Why it matters** — what breaks or what risk it introduces
+4. **Fix** — provide a concrete code suggestion
+
+### Example (from PR #210)
+
+```
+## 🔴 Critical: resize() distorts aspect ratio
+
+**File:** `src/discord.rs`, line ~320
+
+`image::Image::resize(w, h, filter)` resizes the image to the exact
+given dimensions — it does not preserve aspect ratio automatically.
+A 4000×2000 landscape image gets squashed into 1200×1200.
+
+### Fix
+
+​```rust
+let ratio = f64::from(IMAGE_MAX_DIMENSION_PX) / f64::max(w, h);
+let new_w = (f64::from(w) * ratio) as u32;
+let new_h = (f64::from(h) * ratio) as u32;
+img.resize(new_w, new_h, image::imageops::FilterType::Lanczos3)
+​```
+```
+
+## Self-Review Checklist (before opening PR)
+
+Authors should check these before requesting review:
+
+- [ ] **API behavior verified** — read the docs for any new library/function used
+- [ ] **Safety checks preserved** — if refactoring, confirm all original validation/security checks are still present
+- [ ] **Code style consistent** — logging, error handling, naming match the existing codebase
+- [ ] **Tests test the right thing** — assertions reflect actual expected behavior, not just "passes"
+
+## Review Etiquette
+
+- **Be specific** — "this is wrong" is not helpful; show what's wrong and how to fix it
+- **Classify severity** — not everything is a blocker; use 🔴🟡🟢 so the author knows what to prioritize
+- **Acknowledge good work** — if something is well done, say so
+- **One round if possible** — batch all feedback in one review pass to avoid back-and-forth

From a55a7390235610a61e4a5e09fa1d853d229a2d53 Mon Sep 17 00:00:00 2001
From: chaodu-agent <chaodu-agent@users.noreply.github.com>
Date: Sat, 11 Apr 2026 11:32:02 +0000
Subject: [PATCH 2/2] docs: add 4-point review framework to PR review guide

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?
---
 docs/steering/pr-review.md | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/docs/steering/pr-review.md b/docs/steering/pr-review.md
index 662b2616..b56f3845 100644
--- a/docs/steering/pr-review.md
+++ b/docs/steering/pr-review.md
@@ -1,5 +1,14 @@
 # PR Review Guide for openabdev/openab
 
+## Review Framework
+
+When reviewing a PR, always address these four questions:
+
+1. **他解決什麼問題或需求** — 這個 PR 要解決什麼痛點或滿足什麼需求？用白話說明背景。
+2. **他用什麼方式解決** — 具體的技術做法、架構設計、關鍵實作細節。
+3. **他考慮過其他方式嗎** — 從 PR 描述、討論、commit history 中找出被考慮過但沒採用的替代方案，以及為什麼被否決。
+4. **這是目前最好的方式嗎** — 評估現有做法是否最佳，指出可以改進的地方和潛在風險。
+
 ## Severity Levels
 
 Use emoji + color to classify each review comment: