Splitting Changes for Review
Introduction
Welcome back to Review AI-Assisted Python Changes. We are now on lesson 2, building on the verification tax we explored in lesson 1: generated code may arrive quickly, but understanding it still takes time. This time, we will look at what to do when a proposal is too large or combines too many purposes to review reliably. We will practice finding a useful first boundary, planning smaller follow-up batches, and keeping each change understandable and testable.
The Problem: When Volume Makes Review Unreliable
A large diff can make a complete review difficult. When a change mixes several purposes, it is harder to see what each part is meant to do, and a defect can hide among unrelated lines. Reviewers may skim, even when they intend to be careful.
The review rule is straightforward: if we cannot fully understand a change, we should not approve it yet. That does not mean rejecting all the work. We can ask the author to divide the proposal into smaller batches, each with a clear purpose and checks that show whether it works. This builds on our earlier focus on evidence while addressing a different problem: the size and mix of the change itself.
The Running Example: An Oversized Generated Ticket Proposal
Imagine that an AI-assisted proposal changes support tickets in several ways at once. It adds status and closing behavior, assignment, labels, reopening, and unrelated cleanup. Even if every idea might be useful someday, reviewing them together makes it harder to understand and test each one.
For the first useful milestone, we need only to create a ticket, see its status, and close it. Assignment, labels, and reopening can wait for their own batches. Cleanup that is not needed for closing can wait, too. This boundary gives us a small change to understand completely, without claiming that the deferred features are unnecessary forever.
Drawing the Boundary: The Status-Only Contract
The first batch needs a clear contract: a ticket keeps its identifier and title, every new ticket starts as "open", and close() changes its status to "closed". As reviewers, we do not write this code. We write down what the author’s submission in app/tickets.py must do and what evidence will show it:
- A new ticket starts as
"open". Evidence:test_new_ticket_starts_open. - Calling
close()sets the status to"closed". Evidence:test_close_marks_ticket_closed. - The entry point shows the closed ticket. Evidence: Run prints
Ticket #1: closed.
Anything in a submission that these three items do not need does not belong in this batch. This is a useful first milestone because it can run and be tested without assignment, labels, or reopening. A narrow contract also gives us a clear target for review: Does a new ticket start open, and does closing it make it closed?
Proving the Batch Works: Focused Tests and the Entry Point
A small batch still needs evidence. In tests/test_tickets.py, the two focused tests check the starting status and the result of closing. They use the create_ticket helper from app/tickets.py, which stores a new ticket under its identifier in the supplied mapping and returns it:
These checks match the batch contract and show that closing needs no assignment or label feature. In main.py, the example creates ticket 1, closes it, and prints its identifier and status. solution.py calls main(). The package marker app/__init__.py is empty; requirements.txt pins Flake8 and pytest, while .flake8 sets a 100-character line limit. Both checks run from the terminal with python3 -m pytest and python3 -m flake8.
The output confirms that the example reaches the closed state. The focused tests cover the key behavior; the output gives us a quick view of the runnable example.
Recording the Plan: BATCH_PLAN.md
A batch plan makes the boundary visible to the author and reviewer. In BATCH_PLAN.md, the first item names the completed status and closing work; later items separate reopening, assignment, and labels. Each batch should explain its purpose and be runnable and testable on top of its declared prerequisites, so a reviewer can understand the current change without reviewing future work.
The order matters: reopening builds on the status contract, while assignment and labels remain separate features. We can draw those dependencies directly:
“Runnable on its own” does not mean a batch must work without its prerequisites. Reopening cannot exist before tickets have a status, so the reopening batch must run and pass its tests with batch 1 already applied. What it must not do is depend on assignment, labels, or anything else outside its declared prerequisites. The plan does not implement those later features; it records where they could go and what evidence each should include. The Security review section does the same for risk: it records where deeper review will be needed without designing that work now. That lets us review the current batch on its own terms.
Rejecting Unrelated Cleanup and Knowing When Security Review Is Needed
Cleanup that is not required for a batch should stay out of it. If the generated proposal also renames unrelated functions or reorganizes other code, we can request a separate follow-up rather than letting those edits blur the current diff. This keeps the change inspectable and helps us decide whether its stated purpose is complete.
The plan also gives us something to review submissions against. When the author sends batch 1, we compare the diff with the plan: a method from a later batch, or a helper the batch does not need, is a reason to ask for a smaller submission, even if the existing tests pass. Passing tests show that the batch’s behavior works; they do not show that the diff contains only that behavior.
Some follow-up work also changes the risk boundary. For example, restricting who may change a ticket introduces authorization behavior and requires security review. The plan should say so without adding a speculative authorization redesign to the status-only batch. As you may recall from the previous lesson, we classify risk by the behavior involved. Security review is needed because of what the change does, not because AI generated it.
Conclusion and Next Steps
We have practiced judging whether a proposal is small enough to review completely, then dividing an oversized change into ordered batches that can be understood and tested on top of their prerequisites. The ticket’s first batch establishes only its open status and closing behavior, backed by focused tests and a runnable example. Assignment, labels, reopening, unrelated cleanup, and authorization work stay outside that implementation until their own batches are ready. Next, we will put this approach into practice from the reviewer’s seat: planning batches for the generated proposal, reviewing the author’s first-batch submission against that plan, recording what waits and why, and marking where security review applies.
