Reviewable pull requests

Code review starts with the author. A careful reviewer can finish a good change in one sitting. Huge PRs get skimmed. Your job is to make the reviewer's job easy: small diffs, a description for a stranger, and a self-review before you ping anyone.

Aim for under ~400 lines of meaningful diff (generated lockfiles and codegen do not count the same way).

The big idea

When a feature is large, stack changes: foundational refactor → API types → implementation → wiring → tests/docs. Each PR should be mergeable on its own and leave main healthier.

If you cannot explain the change in the PR description without a meeting, the change is probably too big or the design is not settled — split it or write a short design note first.

Walking through it

Write the description for a stranger:

• What changed (one or two sentences).
• Why (ticket, incident, design constraint).
• How you tested (commands, cases, screenshots for UI).
• Risk / rollout (feature flag, migration order, monitoring).

## Summary
Idempotent refund webhook handling keyed on Stripe `event.id`.

## Why
Duplicate deliveries caused double refunds (INC-1842).

## Test plan
- [x] Unit: duplicate event is no-op
- [x] Integration: Postgres unique constraint on stripe_event_id
- [x] Staging: replayed webhook fixture

Open the diff yourself first. Remove debug logs, tighten names, add the test you forgot. Authors who self-review cut a round-trip.

Beyond size, reviewability is local reasoning. A reviewer should validate a hunk without holding the entire system in their head.

• Keep drive-by cleanups out of feature PRs (or make them a stacked prerequisite).
• Prefer additive clarity: // TODO(name): remove after flag default-on beats tribal knowledge.
• Include sample payloads, curl commands, or screenshots when behavior is visual or protocol-heavy.
• Call out intentional weirdness: "Yes, we double-write for two weeks; see migration plan."

Stacked PRs need extra care: rebase when the base changes, keep each description self-contained, and link the stack order in every PR body. Reviewers should be able to land PR 2 without reading PR 4.

Common mistakes

• Megadiff "to start the clock." Unfinished design dumped into review.
• Drive-by cleanups mixed into a feature, burying the risky hunk.
• Description that is a ticket number. A stranger cannot review from that.

Check yourself

1. A feature is 1,200 lines. What is a better shape than one PR?

A stack of mergeable slices: migration, domain logic, handlers, flag — each reviewable in one sitting.

2. What four sections belong in the description?

What, why, how you tested, and risk/rollout.

Key takeaways

• Keep meaningful diffs small; stack large features.
• Write for a stranger: what, why, test plan, rollout.
• Self-review first; keep each stacked PR self-contained.

Further learning

Next: what to look at first.