Review the change against the brief

2197. Lesson identity

Module

5.8 — AI code review

Lesson

Review the change against the brief

Academic type

Debugging Lab

Schema type

practical

Order

1

Estimated time

35–45 minutes, including practice

This lesson treats review as an acceptance decision, not a general opinion about code quality.

2198. Learning objective

After this lesson, you can write a prioritized review of an AI-generated diff by comparing it with the brief, checking its contract, and citing acceptance evidence.

2199. Why this matters

An AI-generated change can compile, look polished, and still solve the wrong problem. A disciplined review protects the requested behavior from scope expansion and catches omissions before they become harder to isolate. In an AI-native workflow, the reviewer is responsible for deciding whether the change is acceptable; the model is not the authority that defines completion.

2200. Prior knowledge

You should already be able to:

• distinguish a requirement from an implementation preference;
• describe a system contract in terms of inputs, outputs, state, and constraints;
• inspect an AI-generated change and compare it with an explicit brief;
• identify the difference between a defect, a scope concern, and a non-blocking style preference.

The previous lesson, 5.7 L2 — Refuse an attractive but unsafe abstraction, established that a smaller, safer change is preferable when a broader abstraction lacks a stable contract.

2201. Core concept

A review is a comparison between three things:

1. Brief: What was requested and what was explicitly excluded.
2. Change: What the diff actually adds, removes, or alters.
3. Evidence: What demonstrates that the requested behavior works and that important existing behavior still holds.

The review should answer two separate questions:

• Contract: Does the implementation satisfy the requested behavior and constraints?
• Scope: Did it change anything that was not necessary for that behavior?

A change can pass one question and fail the other. For example, a feature may work but also modify unrelated systems. That is still a review finding.

2202. Mental model

Use the Brief → Diff → Evidence → Decision model:

Assign severity by its effect on acceptance, not by how strongly you dislike the implementation:

1. Blocking: The change fails a required behavior, violates an explicit acceptance constraint or exclusion, creates a serious regression, or lacks evidence for a required behavior. A blocking finding means the change cannot be accepted until the issue is resolved or the contract is deliberately revised.
2. Important: The change introduces avoidable scope, risk, or maintenance cost, but the available evidence does not show that it currently prevents acceptance or violates a binding constraint. Request correction before acceptance when the risk is material; do not call it blocking without a demonstrated acceptance or contract impact.
3. Non-blocking: The observation concerns clarity, naming, formatting, or another improvement that does not affect the requested behavior, constraints, evidence, or acceptance decision.

Apply this decision policy consistently:

• Accept when no unresolved blocking or important findings remain.
• Request changes when correction is required before acceptance but no blocking finding invokes a formal acceptance gate.
• Block acceptance when any blocking finding remains unresolved.

An explicit exclusion is binding when it protects a stated contract or acceptance boundary. A presentation preference is not. State the consequence and the evidence behind each severity, and do not bury a blocking issue beneath a long list of preferences.

2203. Concrete example

Suppose the brief says:

Add a retry action for a failed request. The action may retry only the failed request, must show a retrying state while the retry is pending, and must not alter unrelated navigation or save-state behavior. Do not introduce a general request framework.

An AI-generated diff:

• adds a retry button;
• retries the failed request;
• changes a shared navigation helper so the screen can be rebuilt;
• introduces a generic RequestController used by only this screen;
• includes a screenshot showing the button after failure;
• does not show behavior while the retry is waiting.

A useful review is not “the code is too abstract.” It is prioritized and tied to the brief:

1. Blocker — missing acceptance evidence: The supplied evidence does not demonstrate the required waiting state during retry. Add a test, trace, or visual artifact that specifically shows the retrying state while the request is pending. Until that evidence exists, the required behavior cannot be accepted.
2. Blocker — explicit scope violation: The change modifies the shared navigation helper even though the brief says not to alter unrelated navigation behavior. Show that the helper change is required by the stated contract and preserves navigation behavior, or remove it and keep the change local. If inspection proves the helper change is isolated and harmless but still unnecessary, record the remaining concern as important rather than claiming a regression that has not been shown.
3. Blocker — explicit exclusion: RequestController is a general framework used by one feature and was explicitly excluded by the brief. Replace it with the smallest local mechanism unless another existing contract demonstrably requires reuse. The issue is blocking because the implementation contradicts a stated boundary, not merely because the reviewer prefers less abstraction.

The screenshot is useful evidence for one state, but it does not prove the complete contract. A clearer screenshot or cleaner naming, by itself, would be a non-blocking observation; missing required behavior or evidence is not.

2204. AI-native workflow

Use AI as a comparison assistant, not as the final reviewer:

1. Give the model the brief, including exclusions and acceptance conditions.
2. Ask it to restate the contract as a checklist without proposing code.
3. Inspect the diff yourself and mark each changed area as required, supporting, or unrelated.
4. Ask the model to compare your inventory with the brief and identify possible omissions or scope expansion.
5. Verify every suggested finding against the actual diff and available evidence.
6. Write the final review in your own priority order, citing the behavior or changed area that supports each finding.

Do not ask, “Does this look good?” That prompt encourages broad approval. Ask questions that expose omissions: “Which brief requirement has no evidence?” and “Which changed area is not necessary for the requested behavior?”

2205. Common mistake

The common mistake is treating successful execution as proof of acceptance. A change can produce the visible result while violating an exclusion, changing a shared contract, or leaving an important state untested. Another frequent mistake is reporting every preference with equal severity, or calling an unnecessary change blocking without identifying the acceptance or contract consequence. A review should reserve blocking for demonstrated acceptance risk, binding constraints, serious regressions, or required evidence gaps; presentation-only improvements remain non-blocking.

2206. Guided practice

Review this fictional brief, commit range, AI-generated summary, and evidence packet.

Brief: Add a hold-to-confirm interaction for a destructive action. The action must complete only after the hold duration is reached, must reset if the pointer leaves the target, and must not change the existing cancel behavior. Keep the implementation local to the action screen.

Commit range: 8c21a4e..9af40bd

AI-generated summary — verify it against the diff: “Adds a local hold-to-confirm interaction with progress and preserves cancellation.”

diff --git a/ui/ActionScreen.ts b/ui/ActionScreen.ts
@@ function onPointerDown() {
+  holdProgress = 0;
+  showHoldProgress();
+  completeDestructiveAction();
 }
@@ function onPointerLeave() {
-  cancelCurrentPress();
+  // Preserve progress so the user can resume the hold.
 }
diff --git a/input/SharedInput.ts b/input/SharedInput.ts
@@ export type InputOptions = {
+  holdMode?: boolean;
 }

Evidence packet:

• progress-50.png shows the progress indicator at 50%;
• cancel-test.txt reports that pressing Cancel still closes the confirmation without completing the action;
• no test, trace, or visual artifact demonstrates completion only after the required duration or reset when the pointer leaves.

Write three findings. For each finding, include:

• priority: blocking, important, or non-blocking;
• the brief clause involved;
• the affected file and symbol or diff hunk, mapped to the relevant brief clause;
• the evidence that is missing or contradictory;
• the requested next action;
• one sentence explaining why the selected priority fits the effect on acceptance.

The incomplete duration contract and the pointer-leave behavior are blocking because they contradict required behavior. The shared input utility is blocking if its use violates the explicit local-scope boundary; if the brief is revised or inspection shows that the utility change is an approved, non-impacting support change, reassess it as important rather than assuming every shared-file change is blocking. Do not label a presentation-only observation, such as clearer progress-indicator labeling, as blocking or important unless it affects a stated requirement.

You must make one explicit decision: accept the change, request changes, or block acceptance. Your decision must follow from your highest-priority finding, not from the number of findings.

2207. Validation / evidence

Your review is complete when it contains:

• a checklist covering every required behavior and every explicit exclusion;
• at least one finding about the incomplete hold-duration contract, classified as blocking;
• at least one finding about the pointer-leave reset requirement, classified as blocking;
• a scope finding about the shared input utility with a severity justified by the stated local-scope boundary and available evidence;
• a clear priority for each finding;
• a concrete next action for every blocking or important finding;
• no inflation of severity for a presentation-only or style observation;
• an accept, request-changes, or block decision supported by the evidence.

A strong submission distinguishes what the summary proves from what it merely suggests. The screenshot can support a progress-display claim, but it cannot prove the duration, reset behavior, cancellation, or completion behavior. Missing evidence for a required behavior is blocking when acceptance cannot be established; a clearer presentation of already-established evidence is non-blocking.

2208. Key takeaways

• Review the brief, the actual diff, and the acceptance evidence as separate sources.
• Check both contract compliance and scope discipline.
• Assign blocking, important, or non-blocking severity according to acceptance impact and evidence.
• Treat missing evidence as a blocking finding when the required behavior cannot otherwise be accepted.
• Use AI to expose omissions, then verify and own the final judgment.

2209. Next lesson

Continue to 5.8 L2 — Find root cause, ownership, and regression risk.

2210. Knowledge check