Review and Change Traceability

Why this matters

An incident review asks who approved the change and why. With linked pull requests the answer is thirty seconds: the diff, the discussion, the checks, the approver. Without them the answer is archaeology through chat logs and memory, and memory loses. Traceability is not paperwork for auditors; it is the team's ability to learn from its own past at speed.

Concepts

A reviewable pull request has four parts: a title naming the change, a description stating why (problem, approach, alternatives rejected), a small diff (one idea, tests included), and green checks. Size is the dominant factor: review quality collapses past a few hundred lines, so split large work into stacked or sequential PRs, each independently coherent. Draft PRs mark work in progress; review requests mark readiness. Never mix the two signals.

Review for what machines cannot check: correctness of the approach, missing edge cases, error handling, security implications, and whether the tests prove anything. Style, formatting and trivial nits belong to linters and formatters, enforced automatically so humans never spend review budget on them. Approve means I understand this and accept responsibility for it running; comment means discuss; request-changes means do not merge until resolved. Rubber stamps are detectable: approvals with no comments on large diffs, repeatedly, from the same pair.

Traceability chains four links: production code to commit (blame), commit to pull request (message references the PR number), PR to issue (linked ticket with the reason), issue to decision (why this approach). Keep the chain unbroken with conventions, not heroics: squash messages that summarize the PR, branch names carrying the issue number, and deploy records naming the commit. Six months later, git blame on any line should answer who, when, what PR, and why, without asking a human.

Worked example

The anatomy of a PR that gets approved in one round:

Title: Cap login retries at 3 with backoff (fixes AUTH-412) Why: brute-force traffic tripled failed logins; unbounded retries amplify it. Chose 3 attempts (matches M03 retry budget lesson). Diff: 40 lines + 25 test lines, rate-limit path only. Checks: unit + integration green, ShellCheck clean.

Expected reading: the title links the issue, the why records the rejected alternative implicitly (unbounded stays unbounded), the diff is one idea with proof, and the checks ran before a human looked. A reviewer verifies the approach in minutes because everything checkable is already checked. Contrast with a 2,000-line refactor titled various fixes: unreviewable by construction, approved by exhaustion, regretted in production.

The common wrong move

Reviewing diffs line by line from the top without reading the description first. It converts review into proofreading: typos caught, design flaws missed. Read the why first, check the tests second, then read the diff with the approach in mind. Ten minutes in that order beats an hour of top-down skimming, and authors should make it easy by writing the why first.

Lab and next step

Lab L12 stages a fictional secret sample in history and requires detection, impact assessment and the correct response order, recorded as a change summary. From here the path continues to M05, where versioned artifacts become runnable ones: containers.