Reviewing Inventory Proposals
Introduction
Welcome back to The Complete Review Cycle. We are in lesson 2, moving from preparing an inventory change to assessing a teammate’s proposal. We will trace how stock adjustments affect the item’s financial value, check what the existing tests actually prove, and record clear, prioritized findings in REVIEW.md. Our role in this lesson is to assess and document risks, not to change the proposed implementation.
Switching Sides: Reviewing Someone Else's Inventory Proposal
In the previous lesson, we prepared a small change from the author’s perspective. Now we switch sides: a teammate has extended the same Item model with a unit price and a total_value method, and we review that proposal against its warehouse requirement, quoted here so we can check every finding against it:
Requirement for this change: Stock can never go below zero. Stock changes only by whole items. An item’s stock value is its quantity × unit price, with exact
Decimalmoney.
You may remember that in lesson 1 we deliberately left out the below-zero check. That was a scope decision for that change, which had no prices and was a first pass. A reviewer judges a change against its own requirement, and this one adds prices, so a wrong quantity now means wrong money. As you may recall from earlier courses, a useful review starts with the behavior and its impact, not with guesses about what the author intended.
We will keep this assessment focused. First, trace the code’s behavior; next, compare it with the existing tests; then document any supported findings. The proposed code stays unchanged. That boundary helps us distinguish reviewing a change from taking over its implementation.
Walking Through the Item Code
In app/inventory.py, Item now stores a name, an integer quantity, and a Decimal unit price. Its adjust_stock method checks that the change is a whole number, then applies it directly to the quantity. Notice what the method does not check: it does not prevent the resulting quantity from dropping below zero.
The proposal already enforces two parts of the item’s contract. The ValueError check keeps stock moving in whole items, and the Decimal price keeps money exact instead of using binary floating-point approximations. Neither rule rejects a valid integer adjustment that leaves the item with negative stock. We will trace that missing boundary next, and we will keep the two existing rules in mind: any later revision must preserve them.
Tracing Negative Stock Through total_value()
The second method in app/inventory.py calculates financial value by multiplying the current quantity by the unit price. Let’s trace a valid integer adjustment that reduces five items by six. The calculation follows the actual stored quantity, even though a warehouse should not have negative stock.
The resulting quantity is -1, so multiplying it by a positive unit price produces a negative financial value:
This is more than an unusual display: it is a correctness risk in warehouse data. The review should explain the connection between adjust_stock, invalid negative stock, and the misleading result from total_value, rather than merely saying that validation is missing.
Reading the Existing Tests and Spotting the Gaps
In tests/test_inventory.py, the current tests check that a normal adjustment changes quantity and that four stocked lamps priced at 25 each have a total value of 100. These are useful ordinary cases, but they do not demonstrate what happens at the boundaries of the calculation.
Running solution.py executes these tests, and both pass. That is real evidence, but only for what the tests check: neither test reduces stock past zero, so a green run says nothing about the defect we just traced.
There is also no test for an item with zero quantity, and the value test uses only a whole-number price. These are test gaps, separate from the demonstrated negative-stock defect. The current code handles both cases correctly; for example, 3 items at Decimal("0.10") already total exactly Decimal("0.30"). Tests would document that behavior and protect it if someone later changes how prices are stored.
Recording Prioritized Findings in REVIEW.md
Now we turn the evidence into review feedback. In REVIEW.md, the first finding is blocking because negative stock conflicts with the warehouse context and leads to a negative financial result. The blocking request also names the test that will prove the fix: a rejected adjustment must leave the quantity unchanged.
The two coverage gaps are worth raising, but they describe missing evidence, not broken behavior. As we learned in earlier courses, blocking is reserved for problems that must be fixed before approval, so these are labeled suggestion (non-blocking). Marking every finding as blocking would hide the one that matters most.
Notice that neither suggestion claims the calculation is broken. Each one states what the tests do not demonstrate and asks for specific evidence. As in earlier review work, we keep every request tied to what the code or tests actually show.
Suggesting the Right Error for Each Failure
The proposal reports invalid input with a generic ValueError. Once the stock boundary is enforced, callers will face two different failures: an invalid request, such as half an item, and a valid whole-number request that exceeds the available stock. We can suggest naming the second case, for example with InsufficientStockError, so callers can handle a shortage specifically. The whole-number check should keep raising ValueError, because a fractional adjustment is an input error, not a stock shortage.
This is a design suggestion, not a demonstrated defect, so it is non-blocking. We are documenting review feedback only: we do not add the exception, alter the implementation, or write new tests in this assessment. Clear priorities help the author fix the blocker first and decide on the suggestions with the full picture.
Conclusion and Next Steps
We traced the proposed behavior from adjust_stock through total_value, identified how negative stock can produce a negative financial result, and checked what the existing tests do and do not prove. The review records one blocking correctness finding with its required regression test, two non-blocking coverage requests, and a non-blocking exception-design suggestion. Running solution.py reproduces the evidence we started from: the proposal’s existing tests pass, even though they miss the defect.
Next, we will put this assessment into practice in three steps: trace the proposal’s behavior, record the blocking finding, and then complete the review with the coverage requests and the exception suggestion. In the next lesson, we will switch back to the author’s side and resolve this exact review.
