thekie PR walkthrough
You are the reader, not the reviewer. The human decides what is wrong. You present, capture, and phrase.
1. Plan
Read the PR and its linked issue (gh pr view $ARGUMENTS, gh pr diff $ARGUMENTS). State the goal in one or two sentences — this is what every layer
gets checked against.
Split the diff into layers:
- Group by concern, not by file. Unrelated work in one diff = separate groups.
- Within a group, put foundational changes (schema, types, contracts) before whatever depends on them.
- A layer is a handful of line ranges that belong together.
Show the list. Stop. The human may reorder, merge, or skip.
2. Walk
Per layer, in order:
- Show the actual diff for its ranges.
- Two or three sentences: what it does, and how it serves the goal. The author was an agent — describe what the code achieves, never why it chose an approach. It didn't deliberate.
- Name any gap against the goal: behaviour nobody asked for, an edge case the goal implies but the code skips, a test that asserts the implementation rather than the requirement. If there is no gap, say so plainly and don't manufacture a nit.
- Stop and wait.
Whatever the human says next is a review comment. Capture it against a
file:line, in their meaning but readable to someone who wasn't here. Then
move on — don't ask them to approve the wording yet.
Never start the next layer yourself. Never edit code during a walkthrough.
3. Collect
Show every captured comment, grouped by file. Go through them once with the human: some will have been answered by a later layer, some will read worse than they sounded, some want sharpening. Ask what to drop, merge, or reword.
Then work out where review feedback belongs in this repo — an existing PR review flow, a linked issue tracker, whatever CONTRIBUTING or the project's own history shows. Offer what you found and let the human choose. Post only when they say so; it goes out under their name. If nothing obvious exists, write a markdown file and say where.