The inherited application

The inventory tool should:

• read warehouse and ledger CSV files;
• normalize and aggregate SKU quantities;
• calculate stock variance;
• write stable text and JSON reports.

It currently does none of this reliably.

The broken-state contract

Each repaired fault lets execution reach the next failure.

Start at the lowest blocked layer

parse
  ↓
import
  ↓
start
  ↓
behavior
  ↓
structure

Do not refactor code that Python cannot import.

Read the traceback from the bottom

Capture four facts:

1. exception type;
2. file and line;
3. failing source text;
4. command that produced it.

That is enough to form the first hypothesis.

Use Copilot inside a boundary

Explain this SyntaxError using only the shown file and traceback.
Identify the smallest syntax repair.
Do not refactor or change behavior.

The prompt asks for a syntax-only change. Check that the proposal stays in scope.

Repair loop

capture failure
  → state one hypothesis
  → make one small change
  → run one narrow check
  → record the result

If the next failure changes, the repair probably moved execution forward.

Prepared demonstration

python -m inventory_reconciliation \
  --warehouse fixtures/input/warehouse.csv \
  --ledger fixtures/input/ledger.csv \
  --output-dir build

Expected first stop: SYN-01 in cli.py.

Narrow checks beat noisy checks

Use the smallest command that can disprove the current hypothesis.

Expected outputs are the contract

SKU     warehouse  ledger  variance  status  severity
AX-100          10      10         0  MATCH   none
BX-200           4       9        -5  SHORT   review
CX-300           0       8        -8  SHORT   urgent

Do not edit the contract to hide a defect.

Intended reconciliation rules

Classification belongs in one place

The starter's duplicated rules disagree. Keep one implementation.

Reproduce each defect with the same fixtures

The same fixtures always expose:

• overwritten duplicate quantities;
• ledger-only SKUs that disappear;
• the wrong urgent threshold;
• stale results on a second call.

Use these repeatable failures to test each diagnosis.

Add tests before changing structure

Keep the fixture-level checks. Add focused tests for:

• severity at absolute variance 6;
• negative quantity rejection with row context.

Refactor only after the tests establish the expected behavior.

Global state creates delayed failures

RUN_HISTORY = []

def reconcile(...):
    RUN_HISTORY.extend(current_results)
    return RUN_HISTORY

The first call may look correct. The second call exposes the leak.

Tangled control flow hides policy

read rows
  + normalize values
  + merge quantities
  + classify variance
  + build output
  + retain state

Separate these jobs so each rule has one implementation.

Target design

cli.py
  → parsing.py
  → service.py
  → rules.py
  → reporting.py

The command-line layer coordinates. It does not own business rules.

Refactor in small moves

1. Remove process-wide mutable results.
2. Extract one classification function.
3. Reuse it from service and reporting.
4. Extract parsing and aggregation.
5. Run tests after each move.

Keep public behavior stable.

Use Python LSP after the tests are green

/lsp show
/lsp test python

Ask for the definition and references of severity_for.
Inspect the actual LSP operation and check its locations.

Then read service.py for inline duplicate rules: they are not necessarily
references to that function.

Approve /plan before structural edits. The lookup uses five minutes of the
existing 25-minute refactor block.

Review Copilot output like a patch

Ask:

• Did the change touch only the current fault?
• Which test proves the claimed behavior?
• Did a rule move or get copied?
• Does output order stay deterministic?
• What assumption is still unproved?

Check generated code against tests and fixtures.

Lab workflow

Final deliverable

• completed repair log;
• runnable inventory command;
• added regression tests;
• unchanged expected outputs;
• clean separation of parsing, rules, service, reporting, and CLI;
• passing pytest -q.