make-pr-easy-to-review

1# Make PR Easy to Review
2 
3Prepare a PR so a reviewer can quickly understand the intent, important files, and risk. The default goal is reviewability without behavior changes.
4 
5## Workflow
6 
71. Resolve the target PR from the user-provided URL or current branch.
82. Inspect commits, diff size, changed paths, generated files, and PR description.
93. Identify reviewability issues: noisy commits, stale description, unrelated changes, mixed mechanical and logic changes, missing tests, or unclear reviewer entry points.
104. Propose a plan before rewriting history or force-pushing.
115. Apply safe improvements, then verify the tree or diff still matches the intended code.
12 
13## History Cleanup
14 
15Only rewrite history when the user asks for it or agrees to the plan. Before rewriting:
16 
17```bash
18gh pr view <PR> --json title,headRefName,baseRefName,state,commits
19git fetch origin <headRefName> <baseRefName>
20ORIGINAL_TREE=$(git rev-parse origin/<headRefName>^{tree})
21```
22 
23Good commit groupings usually follow dependency order:
24 
251. Schema/storage or generated API definitions.
262. Core logic.
273. Wiring and integration.
284. UI or surface behavior.
295. Tests.
30 
31After rewriting, verify content identity:
32 
33```bash
34echo "Original tree: $ORIGINAL_TREE"
35echo "Current tree:  $(git rev-parse HEAD^{tree})"
36git diff origin/<headRefName> --stat
37```
38 
39Do not push if the tree changed unintentionally.
40 
41## Reviewer Guidance
42 
43When code behavior should stay untouched, prefer PR description and review notes:
44…