PR Guide

A worksheet for working with PRs, reviewing someone else’s or planning your own, in a way that builds lasting understanding instead of just relaying a coding agent’s output. Pick a branch and fill it out.

Flow

%%{init: {"themeVariables": {"fontSize": "12px"}}}%%
flowchart TD
    Start{Review or<br/>implement?}
    Start -->|Review| R0[Orient]
    Start -->|Implement| P0[Orient]

    R0 --> R1[My own read]
    R1 --> R2[Check vs agent]
    R2 --> R3[Review pass]
    R3 --> R4[My comments]
    R4 --> RT[Takeaway]

    P0 --> P1[My own plan]
    P1 --> P2[Check vs agent]
    P2 --> P3[Finalize]
    P3 --> PT[Takeaway]

Reviewing a PR

Template: PR Review

• Stage 0: Orient (if unfamiliar with this code)
  • Ask the agent to explain the relevant module/system first
  • Key files involved and what each owns:
  • Existing pattern for this elsewhere in the codebase?
  • My summary, in my own words:
• Stage 1: My own read (cold, before asking anything)
  • Problem this solves:
  • Files changed + role of each:
  • My hypothesis for how it solves it:
  • Anything that looks off/unfamiliar:
• Stage 2: Check myself against the agent
  • Where was I wrong or incomplete?
  • What did I misunderstand about the system?
• Stage 3: Review pass
  • Agent’s findings: 1. 2.
  • Per finding: why does it matter? Could I explain it without the transcript?
• Stage 4: My review comments (own words):
  • Comment 1:
  • Comment 2:
• Takeaway (append to running log):

How long should Stage 1 take?

• Small, mechanical diff (config change, one function, obvious bug fix): a few minutes.
• Typical feature PR (a handful of files, some new logic): 15-30 minutes.
• Core/shared code, data models, auth, or anything unfamiliar: 30-45+ minutes, and that’s fine.
• Better than a timer: stop once you can state intent and approach in 2-3 sentences without looking anything up. If you can’t after a reasonable amount of time on a small diff, that’s a sign to ask the agent to orient you on the surrounding system first, not to push harder alone.

Implementing my own PR

Template: PR Planning

• Stage 0: Orient (if unfamiliar with this code)
  • Ask the agent to explain the relevant module/system first
  • Key files involved and what each owns:
  • Existing pattern for this elsewhere in the codebase?
  • My summary, in my own words:
• Stage 1: My own plan (before asking the agent for one)
  • Problem/goal, in my own words:
  • My approach (what changes, not how): 1. 2.
  • Files/modules touched, and why:
  • Where I’m least sure:
  • Alternative I considered and rejected:
• Stage 2: Compare against the agent
  • Ask for critique on my plan first, not a plan from scratch
  • Where did it disagree? Was it right?
  • Anything it suggested I hadn’t considered?
• Stage 3: Finalize + implement
  • Final plan (merged):
  • Doing myself vs. delegating, and why:
• Takeaway (append to running log):

How detailed should Stage 1 be?

• Enough that a teammate could poke a hole in it, not enough that you’re writing pseudocode.
• Name what changes and why, not how. If you’re writing function signatures or exact file edits, you’ve gone too deep for this stage.
• If you can’t name which files/modules are involved at all, you haven’t gone deep enough yet, that’s a sign to go back to Stage 0.