Complete Inventory Review Cycle
Introduction
Welcome to The Complete Review Cycle. We are beginning lesson 1, where we take the author’s side of a warehouse inventory change and prepare it for review. Skills from earlier courses, such as inspecting a full diff, writing a focused pull request description, and running local checks, now come together in one small project. Our goal is to build a direct stock adjustment, keep the change within its intended scope, and explain it clearly so a reviewer can understand what changed and why.
The Warehouse Inventory Requirement
Warehouse staff need to keep item counts accurate as shipments arrive and orders leave. For this first version, we will represent those events with a simple quantity adjustment: a positive integer adds stock, and a negative integer removes it. We are deliberately leaving out validation (for example, stopping stock from going below zero), pricing, and persistence. As in our earlier YAGNI discussions, the goal is the smallest design that meets the requirement, not a framework for needs we do not have yet. A clear boundary makes the change easier to build and review.
Modeling an Item: The Item Class and adjust_stock()
We begin in app/inventory.py with the item itself. The constructor stores the provided name and starting quantity on the new object. Then adjust_stock adds the supplied amount to that stored quantity. Notice that the method does not need separate paths for shipments and orders: adding a positive amount raises the count, while adding a negative amount lowers it. This keeps the behavior direct and easy to trace. We are not adding checks or extra rules because they are outside this pass’s stated scope.
The += operation updates the quantity on the same item instance. For example, a quantity of 10 adjusted by 5 becomes 15; an adjustment of -2 would reduce it by two. Keeping this method small gives callers one consistent operation for both directions of stock movement.
A Lightweight Inventory Container
Next, we add two helpers in app/inventory.py. create_inventory gives us a fresh, empty dictionary. add_item creates an Item, stores it under its name, and returns the object so the caller can use it right away. For this first pass, a dictionary is enough to connect names to items; a custom storage system would add complexity without meeting any additional requirements. Keeping the model and helpers together also gives the example and tests one shared source of inventory behavior.
The dictionary stores each item under its name, while the returned value is the same object stored in the inventory. That lets the example adjust the item directly while keeping it registered in the inventory.
Running the Example: main.py
Now we can follow the workflow in main.py: create the inventory, register a Widget with an initial quantity of 10, adjust it by 5, and display its name and updated quantity. The main function groups the example steps, and the final condition runs them when this file is used as the program’s entry point. The separate solution.py launcher imports and calls main, providing the task runner with a simple way to start the example. This small run is a useful manual check alongside the focused tests.
Running the example prints the resulting quantity:
The output confirms the full path from creating and storing an item to changing and displaying its quantity. This is the same kind of quick entry point we used in earlier courses as one local check of a change.
Verifying with a Focused Test
In tests/test_inventory.py, each test sets up an inventory and a Widget, performs one adjustment, and then checks the quantity. This follows the precondition, action, assertion structure from earlier courses: establish the starting state, apply the behavior, and verify the meaningful result. The requirement defines two directions, so we write one test for each: a positive adjustment raises the quantity from 10 to 15, and a negative adjustment lowers it from 10 to 6. Each assertion checks the resulting quantity, rather than merely checking that an item exists. Two focused tests are a good fit for this small change because together they cover both behaviors we promised.
The inventory variable establishes each test’s starting context, and add_item gives it an item to adjust. Either assertion would fail if the adjustment did not update the item’s stored quantity as expected. Running pytest -q shows what actually happened:
Each dot is one passing test. This observed result, not the fact that we wrote the tests, is the evidence a reviewer can rely on.
Self-Reviewing the Diff
Before asking someone else to review the change, we inspect the complete diff, including app/inventory.py, main.py, and tests/test_inventory.py. This is the same self-review habit we practiced earlier: read the changed lines in context, not just the main method. Check that the Widget example still demonstrates the intended behavior, that each test checks the resulting quantity, and that the implementation has no accidental debugging output or unrelated edits. We are not trying to expand the feature during review; we are confirming that this proposal is clean and matches its stated scope.
- Look for temporary values, unused code, and stray print statements.
- Confirm that the example shows
10becoming15, and that the two tests cover the increase and the decrease. - Remove unrelated edits so reviewers can focus on this feature.
Writing the PR Description
The final part of the proposal is PR_DESCRIPTION.md. Its four sections answer practical review questions: what changed, why it matters, how it was checked, and what is intentionally excluded. The scope statement is especially useful: naming the below-zero check and price calculations as out of scope helps prevent reviewers from expecting them in this change. As before, we record only checks that were actually run, together with what we observed: the command and its result, not just that a test exists. The description should make the review easier, not overstate our verification.
Together, these sections give reviewers a concise account of the feature’s purpose, evidence, and boundaries. The description keeps attention on the direct adjustment behavior rather than future inventory work.
Conclusion and Next Steps
We have drafted the author side of a small inventory change: an Item model, lightweight inventory helpers, a runnable Widget example, focused quantity tests for both directions, a clean diff, and a PR description that explains purpose, observed results, and scope. These pieces work together to make the proposal understandable and reviewable without adding features the requirement does not call for. Next, we will put these ideas into practice in three steps: implement the Item constructor and adjust_stock, write a PR description that states what changed, why, how it was checked (with the results you observed), and what is out of scope, and then self-review a supplied version of the change to remove accidental edits before requesting review. In the next lesson, a teammate will build on this same Item model by adding prices, and we will switch sides to review their proposal. A boundary we deliberately skipped here will matter there.
