DEV Community: Dakota Huang

Capture Coupon Order Before One Rate Extract

Dakota Huang — Sat, 10 Oct 2026 12:48:22 +0000

Capture Coupon Order Before One Rate Extract

Pin coupon order before you extract one rate function. A mixed checkout hides stacking, mutation, and file writes in one body. Move only the pure rate math after those edges hold.

The cut this article defends

A wide helper can change cents without a red test. Coupon order and member rate often share one block. Pin both, then move the smallest pure piece.

This draft does not claim a measured production incident. It uses a small unexecuted example to show the sequence. Run the commands yourself before you trust the baseline.

The messy function

Treat the listing below as unexecuted proposal code only. It is not a billing service, a tax engine, or an audit. It only exposes the mixed behavior you should not split blindly.

from decimal import Decimal, ROUND_HALF_UP
from pathlib import Path

def checkout(cart, coupon, dest):
    total = Decimal('0')
    for item in cart['items']:
        total += Decimal(str(item['price'])) * item['qty']
        cart['seen'] = cart.get('seen', 0) + 1
    if coupon == 'SAVE10':
        total = total * Decimal('0.90')
    elif coupon == 'FIVE':
        total = total - Decimal('5.00')
    if cart.get('member'):
        total = total * Decimal('0.95')
    total = total.quantize(Decimal('0.01'), rounding=ROUND_HALF_UP)
    Path(dest).write_text(str(total))
    return total

Three distinct smells sit inside that one function. The loop mutates cart while it sums prices. A percent coupon and a member rate stack in fixed order.

The same call writes a file before it returns. Those smells need different tests and different diffs. A pure extract can keep the math and still drop the mutation.

A file move can change path errors without touching cents. Split one concern only after each pinned edge is green. Leave the write and the mutation in the wrapper.

What the tests must lock

Lock six observable edges before any rename or move. Empty carts, stacked rates, negative results, and file text all count. Skip any edge and the later extract can lie.

Use these fixtures as the contract rows for the suite. Prices stay strings so binary float noise never enters. Expected cents come from a capture run, not from memory.

Row	Items	Coupon	Member	Also assert
E1	none	none	no	return text, missing seen, file text
E2	10.00 x2	SAVE10	yes	SAVE10 before member, seen equals 1
E3	1.00 x1	FIVE	no	current negative total, file matches
E4	1.015 x1	none	no	captured half-up text, not a guess
E5	1.00 and 2.50	none	no	seen equals 2, sum text
E6	10.00 x1	FIVE	yes	FIVE before member rate

Do not hand-guess the half-up row in that table. Decimal half-up on a third digit is easy to misremember. Capture the return text once, then paste that string.

Read the decimal quantize notes beside your capture. The official library page is the primary source for that rule. A blog memory of 1.005 is not a contract.

The FIVE row may show a negative total today. Pin that sign when the current function returns it. Do not fix the sign in the same change as the extract.

Steps

1. Freeze the module boundary

Copy checkout into a tiny module named checkout_mix.py. Import it from the test file without editing the body. A cleanup during the copy hides the baseline you need.

2. Add a capture command

Print six rows before you write any assertions. Each row should show return text, seen count, and file text. Save that transcript beside the tests as a golden file.

import tempfile
from pathlib import Path
from checkout_mix import checkout

ROWS = [
    ('E1', {'items': []}, None),
    ('E2', {'items': [{'price': '10.00', 'qty': 2}], 'member': True}, 'SAVE10'),
    ('E3', {'items': [{'price': '1.00', 'qty': 1}]}, 'FIVE'),
    ('E4', {'items': [{'price': '1.015', 'qty': 1}]}, None),
    ('E5', {'items': [{'price': '1.00', 'qty': 1}, {'price': '2.50', 'qty': 1}]}, None),
    ('E6', {'items': [{'price': '10.00', 'qty': 1}], 'member': True}, 'FIVE'),
]

def main():
    lines = []
    with tempfile.TemporaryDirectory() as raw:
        root = Path(raw)
        for name, cart, coupon in ROWS:
            dest = root / (name + '.txt')
            got = checkout(cart, coupon, dest)
            seen = cart.get('seen', 'missing')
            line = name + '|' + str(got) + '|' + str(seen) + '|' + dest.read_text()
            lines.append(line)
    print('\n'.join(lines))

if __name__ == '__main__':
    main()

The capture script should call the current function only. It should not import the future helper or a new path. If the script fails, stop and fix the fixture data.

python capture_checkout.py > tests/golden_checkout.txt

That redirect is a proposal command, not a recorded run. Review the golden file before you convert rows into asserts. A blank line or a traceback means the baseline is not ready.

3. Turn the transcript into tests

Write one test function for each row in the table. Assert the return value, the destination text, and the seen count. Use tmp_path so the file write stays inside the sandbox.

from checkout_mix import checkout

def test_save10_then_member_rate(tmp_path):
    cart = {
        'items': [{'price': '10.00', 'qty': 2}],
        'member': True,
    }
    dest = tmp_path / 'total.txt'
    got = checkout(cart, 'SAVE10', dest)
    assert str(got) == '17.10'
    assert dest.read_text() == '17.10'
    assert cart['seen'] == 1

def test_half_up_row_matches_capture(tmp_path):
    cart = {'items': [{'price': '1.015', 'qty': 1}]}
    dest = tmp_path / 'total.txt'
    got = checkout(cart, None, dest)
    captured = 'PASTE_FROM_GOLDEN_FILE'
    assert str(got) == captured
    assert dest.read_text() == captured
    assert cart['seen'] == 1

The SAVE10 example uses values that stay exact in Decimal. Twenty dollars times 0.90 then times 0.95 equals 17.10. Confirm that string in the golden file before you lock it.

The half-up test must not ship with a guessed cent string. Paste the captured token in place of the placeholder. A later mismatch means rounding moved, not that the file drifted alone.

4. Run tests against unchanged code

The first green run is the baseline, not a refactor win. If a test fails now, the assertion guessed the wrong text. Change the test until it matches the current function.

python -m pytest tests/test_checkout_mix.py -q

Keep this command stable for the later rerun. A new flag or a new marker can hide a miss. The same command is the comparison you want.

5. Extract only the pure rate function

Move only the arithmetic into a helper named apply_rates. Pass a Decimal, a coupon string, and a member flag. Do not pass cart, dest, or Path into that helper.

def apply_rates(total, coupon, member):
    if coupon == 'SAVE10':
        total = total * Decimal('0.90')
    elif coupon == 'FIVE':
        total = total - Decimal('5.00')
    if member:
        total = total * Decimal('0.95')
    return total.quantize(Decimal('0.01'), rounding=ROUND_HALF_UP)

def checkout(cart, coupon, dest):
    total = Decimal('0')
    for item in cart['items']:
        total += Decimal(str(item['price'])) * item['qty']
        cart['seen'] = cart.get('seen', 0) + 1
    member = bool(cart.get('member'))
    total = apply_rates(total, coupon, member)
    Path(dest).write_text(str(total))
    return total

The wrapper still owns the loop, the mutation, and the write. The public signature of checkout stays the same. The diff should stay small enough to read in one pass.

Passing a bool of the member field keeps the old truth check. A missing member still behaves as false under that check. Do not invent a default member policy in this diff.

6. Re-run the same six tests

Do not add assertions in this same diff. A new rule, such as banning negative totals, is a later change. Green tests mean the pinned edges survived the move.

python -m pytest tests/test_checkout_mix.py -q
git diff -- checkout_mix.py

Read the diff before you commit the extract. You should see one new function and one call site. You should not see a changed coupon string or a network import.

7. Reject a wider helper

Stop if the new function opens files or reads env vars. Stop if it mutates cart or renames public callers. Stop if you cannot explain the change in four lines.

Decision table

Signal you see	Smallest safe action	Do not do this
Math mixed with a file write	Extract rate math only	Move Path into the helper
First test run fails	Fix the assertion	Edit checkout to satisfy a guess
Negative FIVE result	Pin the current sign	Clamp to zero in this diff
seen key untested	Add the mutation assert	Extract the loop and the write
Half-up value unclear	Paste the captured string	Type a remembered cent value
Helper needs the cart dict	Pass plain inputs instead	Share the mutable cart

Use the table when a review comment asks for a bigger split. The right column is a stop rule, not a style preference. A wider helper waits for its own pinned edges.

Failures this sequence is meant to catch

Test and extract in one commit, and blame becomes unclear. You cannot tell whether the assert or the math moved. Split those commits even when the change feels small.

Asserting file text alone still misses a return drift. The function can write the new text and return it too. Pin both sides, plus the seen count, on every row.

Sharing the cart dict into the helper moves the mutation. Seen counts then depend on call order inside the helper. Pass plain inputs so the loop remains the only writer.

Updating the golden file after the extract blesses the bug. The capture step is legal only on unchanged code. A post-extract refresh is a behavior change with extra steps.

Using float literals for prices makes the pin unstable. Binary fractions can change the cent you meant to lock. Keep price strings and Decimal conversion in one place.

Where a free runner fits

A free model can list candidate rows from the messy function. Keep a row only when you can trace it to current code. Delete any row that invents a tax rule or a currency.

Disclosure: This article was prepared as part of MonkeyCode's product outreach. MonkeyCode's free model access can draft that candidate row list. MonkeyCode's free server option can run the same pytest command.

Both claims here are availability only, not a speed benchmark. No customer count, quota, or hardware detail is stated here. The note above is a relationship label, not a test result.

Use the server run as a second green check. A local pass can hide an edited file or a shadowed package. A remote pass still does not prove the money rule is complete.

Do not send secrets, customer carts, or private prices remotely. Use the synthetic rows from this article, or rows you may share. If the server locale differs, avoid locale-formatted money strings.

Limits of this cut

This sequence preserves behavior on the pinned rows only. It does not certify tax, coupons, or member policy. A captured negative total can still be the wrong product rule.

The sample ignores currency codes and concurrent cart edits. It also ignores permission errors on the destination path. Those gaps need their own tests before you call the module safe.

The pure helper still uses ROUND_HALF_UP from the old function. That mode is a captured choice, not a universal ledger law. Another codebase may need a different rounding mode entirely.

This text did not execute the sample or the capture script. Treat every expected string you did not capture as unverified. Run the capture command before you merge the extract.

Who should skip this cut

Skip this cut when you cannot run tests on the real module. A paper extract without a green baseline is only a rewrite. You will not know which edge moved during the split.

Skip it when the next change must alter totals on purpose. Characterization tests will fail until you update those rows. That failure is useful, but it is the wrong tool here.

Skip it when money rules are still undecided by the owner. Pinning a guess freezes the wrong contract into the suite. Wait until the current function is the source you mean to keep.

Skip it for a live incident hotfix with no fixture data. The smallest safe act then is a guarded revert or a flag. Do not learn the contract while production is still failing.

Close

Hold the six edges, then move one pure function. Leave mutation and file writes in the wrapper for now. A smaller diff is easier to reject when a cent changes.

If a MonkeyCode account is already available, draft rows with the free model. Then run that same pytest file on the free server before merge.

Freeze Aging Labels Before One Status Extract

Dakota Huang — Sat, 10 Oct 2026 09:24:01 +0000

Freeze Aging Labels Before One Status Extract

Pin current aging labels before you trust a cleanup diff. Extract one status rule only after those labels stay identical. A wider split hides label bugs inside unrelated edits.

Do not start this refactor with a broad cleanup. Record the labels, cents, and stderr lines first. Then move one function and stop the edit.

Why this cut stays small

A mixed diff is hard to review under time pressure. Reviewers cannot see which hunk changed a bucket. A one-function extract keeps that question small.

The inherited function also prints a debug line. That print is observed behavior, not harmless noise. Tests should fail if the line moves or vanishes.

The function you inherit

The sample below is a worked fixture, not a production trace. It mixes status labels, cent rounding, and a stderr print. Read the listing as unexecuted example code only.

# aging.py — unexecuted example, not a production trace
import sys

def build_aging_row(amount, days_overdue):
    cents = int(round(float(amount) * 100))
    if days_overdue is None or days_overdue <= 0:
        label = "current"
    elif days_overdue <= 30:
        label = "1-30"
    elif days_overdue <= 60:
        label = "31-60"
    elif days_overdue <= 90:
        label = "61-90"
    else:
        label = "90+"
    print(f"aging {label} {cents}", file=sys.stderr)
    return {"cents": cents, "label": label}

Missing days become the label current in this fixture. Negative days follow that same branch today too. Leave both paths untouched during this status extract.

Rounding stays inside the caller for this pass. The status rule is the only code that moves. That boundary is the entire point of the cut.

What the golden file must hold

Freeze three fields for every pinned fixture row. Freeze the label string and the cent integer. Freeze the exact stderr line, including its trailing newline.

Do not assert the finance rule you wish were true. Assert the values this interpreter emits today. A later ticket can change those values on purpose.

Inputs worth pinning

Cover the bucket edges and the missing-day path. Use a plain amount so float noise stays out. Store outputs in a golden file after one local capture.

The table lists inputs and the reason for each row. It does not list cents, because those come from capture. Hand-typed cents are how golden files go stale.

amount	days_overdue	why this row exists
10	0	non-positive days map to current
10	None	missing days stay on the current path
10	30	last day inside the 1-30 bucket
10	31	first day inside the 31-60 bucket
10	60	last day inside the 31-60 bucket
10	61	first day inside the 61-90 bucket
10	90	last day inside the 61-90 bucket
10	91	first day inside the 90+ bucket
0	-1	negative days stay on the current path

Skip live ledgers, clocks, and network calls here. Those inputs will not replay on a second run. This lesson needs rows you can execute twice.

Steps to seal, then extract

1. Put the fixture in one folder

Keep the module and the test side by side. Do not import the real billing package yet. A tiny folder makes the diff easy to read.

Name the files so the review stays obvious. The tree below is the whole fixture for this pass. Keep production billing code outside this folder.

aging.py
aging_cases.py
capture_aging.py
test_aging_characterize.py
golden_aging.json

Share one case list between capture and compare. Two copied lists will drift on the next edit. The helper below is the single source for rows.

# aging_cases.py — unexecuted example
import contextlib
import io

CASES = [
    {"amount": "10", "days_overdue": 0},
    {"amount": "10", "days_overdue": None},
    {"amount": "10", "days_overdue": 30},
    {"amount": "10", "days_overdue": 31},
    {"amount": "10", "days_overdue": 60},
    {"amount": "10", "days_overdue": 61},
    {"amount": "10", "days_overdue": 90},
    {"amount": "10", "days_overdue": 91},
    {"amount": "0", "days_overdue": -1},
]

def collect(build_row):
    found = []
    for case in CASES:
        buf = io.StringIO()
        with contextlib.redirect_stderr(buf):
            row = build_row(case["amount"], case["days_overdue"])
        found.append({
            "amount": case["amount"],
            "days_overdue": case["days_overdue"],
            "cents": row["cents"],
            "label": row["label"],
            "stderr": buf.getvalue(),
        })
    return found

2. Capture outputs before any edit

Run the capture once on your own machine. Commit the golden file beside the compare test. Do not hand-type observed cents from memory later.

# capture_aging.py — unexecuted example
import json
from pathlib import Path
import aging
from aging_cases import collect

def main():
    path = Path("golden_aging.json")
    payload = collect(aging.build_aging_row)
    path.write_text(json.dumps(payload, indent=2) + "\n", encoding="utf-8")
    print(path.name)

if __name__ == "__main__":
    main()

python capture_aging.py
python -m json.tool golden_aging.json > /dev/null

Check that the sealed file is valid JSON. A parser check is not a behavior check. It only proves the next compare can load the seal.

The redirect above is a Unix shell example. Use your shell's null device if the path differs.

3. Compare on every later run

The compare test reads the golden file and fails on drift. It must not rewrite the file during compare. A quiet rewrite would hide a bad extract.

# test_aging_characterize.py — unexecuted example
import json
from pathlib import Path
import aging
from aging_cases import collect

def test_aging_matches_golden():
    path = Path("golden_aging.json")
    assert path.exists(), "run capture_aging.py before compare"
    expected = json.loads(path.read_text(encoding="utf-8"))
    found = collect(aging.build_aging_row)
    assert found == expected

Install pytest in that folder before the compare run. A green run means the sealed rows still match. It does not mean the labels match a finance policy.

python -m pytest test_aging_characterize.py -q

Keep those two judgments in separate reviews. Policy checks belong with an intended label change. This file only guards the seal you just wrote.

4. Write the extract as a proposal

Move only the branch that picks the label. Call the new helper from the old function. Leave rounding, printing, and return keys in place.

# proposed aging.py — unexecuted proposal, not a measured result
import sys

def label_for_days(days_overdue):
    if days_overdue is None or days_overdue <= 0:
        return "current"
    if days_overdue <= 30:
        return "1-30"
    if days_overdue <= 60:
        return "31-60"
    if days_overdue <= 90:
        return "61-90"
    return "90+"

def build_aging_row(amount, days_overdue):
    cents = int(round(float(amount) * 100))
    label = label_for_days(days_overdue)
    print(f"aging {label} {cents}", file=sys.stderr)
    return {"cents": cents, "label": label}

Treat the helper listing as a proposal, not a measured result. Run the compare test before you trust the move. Reject the patch if any golden row changes.

5. Reject diffs that do extra work

Read the diff before you read any explanation. Count the functions that the patch actually touches. Accept one new helper and one call site only.

git diff --unified=3 -- aging.py

Golden row changes mean behavior moved, so reject them. Stderr changes mean the print drifted, so reject them. A new dependency means the cut grew, so reject it.

diff signal	decision	reason
golden rows differ	reject	behavior moved, not only structure
stderr text differs	reject	the print is part of the seal
rounding expression changes	reject	that edit is a second refactor
missing-day branch changes	reject	a bug fix belongs in a later ticket
new dependency added	reject	this extract needs no new package
only the label helper is added	accept	this is the smallest safe cut

A model often repairs the missing-day path while extracting. That extra repair fails the written decision table. The table outranks a fluent explanation of the fix.

6. Stop after the green compare

Do not extract rounding in the same change. Do not delete the stderr print in this pass. One green extract is the end of this ticket.

Open a second ticket for intended behavior changes. That ticket should edit the golden file on purpose. Reviewers can then see the intended label shift.

Where a free model can help

You can ask a free model to draft the helper. Give it a short constraint, and demand a diff. Do not ask it to rewrite the module as an essay.

Disclosure: This article was prepared as part of MonkeyCode's product outreach. MonkeyCode free model access can draft that constrained extract. You can run the same pytest command on the free server option.

Use either path only on this fixture, which holds no secrets. Treat the prompt text as a sketch, not a product contract. Availability here is an operator-supplied claim for this draft.

Extract label_for_days from build_aging_row.
Do not change rounding, prints, keys, or None handling.
Do not add dependencies.
Return a unified diff only.

It is not a promise about quotas, hardware, or duration. Paste the returned diff back into your tree. Run the compare test on a machine you control.

A green server run is a hint, not a release decision. Server images can differ from your laptop interpreter. Re-run the compare where you will merge the patch.

Limits of this gate

Characterization tests lock today's behavior, including known mistakes. They are not a proof of correct finance rules. They also do not measure thread safety or speed.

Python 3 round uses half-to-even for exact ties. This fixture avoids tie amounts so that rule stays idle. See the round docs for that tie rule.

The golden file belongs to the interpreter that sealed it. A different build can still surprise you on other amounts. That is why these rows use the amount string 10.

Do not upload customer rows to a free server. The sample has no names, accounts, or secret keys. A real ledger extract would be the wrong payload.

Free model access can change or end later. This workflow still works with a local editor alone. The tests, not the tool, hold the safety line.

Who should skip this pass

Skip this pass if the ticket must change labels now. Write a failing policy test for the new rule. Then edit the golden file inside that same review.

Skip it when inputs include clocks, randomness, or live HTTP. Seal those edges first, or the compare will flap. Flapping tests teach people to ignore red runs.

Skip it if you cannot explain the missing-day path. Preserving a mystery is not a safe cut. Read that branch, pin it, and only then move it.

What to do next

After this extract stays green, stop the cleanup. Queue a separate change for rounding or missing days. Each change should update the golden file in clear view.

The merge rule is small enough to repeat on the next module. Pin the rows, move one rule, and compare again. Reject any diff that quietly does a second job.

If you already have that free model access, use it here. Let it draft the helper, then let the compare test decide. Skip the tool when you cannot read the resulting diff.

Five Discount Rows Are the Refactor Gate

Dakota Huang — Sat, 10 Oct 2026 02:41:40 +0000

Five Discount Rows Are the Refactor Gate

Current discount behavior should stay pinned before any formula moves. A wide edit can change totals while tests still look green. Five recorded rows are enough to stop that silent shift.

The method is a characterization gate, then one extract. It does not fix known rounding bugs in the same change. A bug fix is a later commit with its own rows.

Why a wide cleanup fails

Messy discount code often mixes math, environment reads, and prints. A cleanup that touches all three can change money output. Reviewers then argue about style instead of totals.

Integer floor division is the hazard in this sample. A rate of fifteen on one hundred ninety-nine cents yields twenty-nine. A later half-up rule would be a different commit.

That one-cent gap is enough to hide inside a refactor. The gate records the old cent, not the preferred cent. Preference belongs in a separate reviewed change later.

The only function this pass may touch

The sample below is a proposal, not a production billing module. It reads two environment variables and mutates the order dict. It also prints a discount line through an injected sink.

import os

def apply_discount(order, sink=print):
    rate = os.environ.get("DISCOUNT_RATE", "10")
    cap = os.environ.get("DISCOUNT_CAP", "50")
    subtotal = order["subtotal"]
    raw = subtotal * int(rate) // 100
    discount = raw if raw < int(cap) else int(cap)
    order["discount"] = discount
    order["total"] = subtotal - discount
    sink(f"discount={discount}")
    return order["total"]

Three side effects sit beside the formula itself. The order dict gains discount and total keys. The sink receives one formatted discount line each call.

The process environment supplies both rate and cap. Moving all three at once is not the smallest safe change. The smallest change lifts only the arithmetic block.

Environment reads, mutation, and printing stay in the wrapper. Callers keep the same function name and the same arguments. That boundary is the whole point of this pass.

Rows that hold the old cents

Each row fixes subtotal, rate, cap, discount, total, and the printed line. A missing rate or cap means the default string is in force. Negative subtotal is included because the current code allows it.

Row	Subtotal	Rate	Cap	Discount	Total	Line
1	199	15	50	29	170	discount=29
2	1000	15	50	50	950	discount=50
3	80	default	default	8	72	discount=8
4	0	10	50	0	0	discount=0
5	-100	10	50	-10	-90	discount=-10

Row one uses floor division on one hundred ninety-nine cents. That subtotal times fifteen is two thousand nine hundred eighty-five. Integer division by one hundred then yields twenty-nine.

Twenty-nine is under the cap, so the cap does not apply. The returned total is one hundred seventy cents. The printed line must match that same discount.

Row two exceeds the cap on a one thousand cent subtotal. One thousand times fifteen divided by one hundred is one hundred fifty. The comparison uses less-than, so one hundred fifty becomes fifty.

The pinned total is nine hundred fifty cents. A test that checks only this row can still pass. A small formula drift can hide behind the cap.

Row one is what catches the one-cent case. Row three checks the default rate and the default cap. Eighty times ten divided by one hundred is eight.

Eight is under the default cap of fifty. The printed line is still emitted for that row. Defaults are behavior, not comments beside the code.

Editing the default strings is a behavior change. Row five is a preserved quirk, not a billing rule. Negative ten is less than fifty, so the cap does not clamp it.

Do not treat that row as a product requirement. Python floor division makes negative one hundred times ten land on negative ten. That result is pinned only so the extract stays honest.

1. Store the rows as data

Keep the expected numbers together in one list. Loop the list so a new row is data, not a new test name. Use monkeypatch so environment edits do not leak.

from discount_legacy import apply_discount

ROWS = [
    {
        "subtotal": 199,
        "rate": "15",
        "cap": "50",
        "discount": 29,
        "total": 170,
        "line": "discount=29",
    },
    {
        "subtotal": 1000,
        "rate": "15",
        "cap": "50",
        "discount": 50,
        "total": 950,
        "line": "discount=50",
    },
    {
        "subtotal": 80,
        "rate": None,
        "cap": None,
        "discount": 8,
        "total": 72,
        "line": "discount=8",
    },
    {
        "subtotal": 0,
        "rate": "10",
        "cap": "50",
        "discount": 0,
        "total": 0,
        "line": "discount=0",
    },
    {
        "subtotal": -100,
        "rate": "10",
        "cap": "50",
        "discount": -10,
        "total": -90,
        "line": "discount=-10",
    },
]

def _apply_env(monkeypatch, row):
    if row["rate"] is None:
        monkeypatch.delenv("DISCOUNT_RATE", raising=False)
    else:
        monkeypatch.setenv("DISCOUNT_RATE", row["rate"])
    if row["cap"] is None:
        monkeypatch.delenv("DISCOUNT_CAP", raising=False)
    else:
        monkeypatch.setenv("DISCOUNT_CAP", row["cap"])

def test_discount_rows_hold(monkeypatch):
    for row in ROWS:
        _apply_env(monkeypatch, row)
        lines = []
        order = {"subtotal": row["subtotal"]}
        total = apply_discount(order, sink=lines.append)
        assert total == row["total"]
        assert order["discount"] == row["discount"]
        assert order["total"] == row["total"]
        assert lines == [row["line"]]

Run the gate before any edit to the formula. The commands assume pytest is installed in the active environment. A failing import means the module path is wrong.

python -m pytest tests/test_discount_rows.py -q

A green run means the five rows match this checkout. A red run means the table is wrong for this tree. Fix the table before you extract any formula.

2. Force a known failure

Add one cent to the floor result in a scratch copy. Do not commit that probe to the branch. The point is to prove the rows can fail.

raw = subtotal * int(rate) // 100 + 1

Row one then expects thirty instead of twenty-nine. The pinned assertion fails on that changed total. The failure comes from integer arithmetic alone here.

Row two stays capped, so it may still pass. Row one is the probe that must fail. A cap-only test would miss this one-cent shift.

Restore the floor operator after the probe ends. The characterization file should be green again afterward. If it stays red, the probe leaked into the branch.

Check the diff before you continue. The scratch edit should be gone from the diff. A leftover plus-one is already a behavior change.

git diff -- discount_legacy.py

Do not extract on top of a dirty probe. A clean diff is the entry ticket for step three. The characterization file should still be the only new test.

3. Lift one pure function

Create one pure function with the same floor rule. Keep the same less-than cap comparison inside it. Leave environment access inside the existing public wrapper.

Leave the print line inside that same wrapper. The public wrapper signature stays the same after extract. Callers that pass a sink still work unchanged.

def discount_amount(subtotal, rate, cap):
    raw = int(subtotal) * int(rate) // 100
    limit = int(cap)
    if raw < limit:
        return raw
    return limit

def apply_discount(order, sink=print):
    rate = os.environ.get("DISCOUNT_RATE", "10")
    cap = os.environ.get("DISCOUNT_CAP", "50")
    discount = discount_amount(order["subtotal"], rate, cap)
    order["discount"] = discount
    order["total"] = order["subtotal"] - discount
    sink(f"discount={discount}")
    return order["total"]

Callers that rely on dict mutation still work. Re-run the same test file after the extract. Do not add new assertions in this commit.

python -m pytest tests/test_discount_rows.py -q
git diff --stat -- discount_legacy.py

A passing run with a small diff is the stop condition. The diff should show one new function and one call site. It should not show a rounding policy change.

4. Decide with a table, not a debate

Stop when the rows pass and the diff is only the extract. Continue only if a listed signal appears below. Each listed signal maps to one action only.

Signal	Action
Rows fail after the extract	Revert the extract and compare operators
Diff edits the print format	Move that edit to a later commit
Diff edits default rate or cap	Revert it; row three pins those defaults
Diff replaces floor division	Reject it; that is a behavior change
Rows pass and the diff is one function	Stop and file rounding as a separate ticket

The table is the review checklist for this extract. It is shorter than a style debate in review. It also names the forbidden second change clearly.

5. Draft assertions, then delete extras

MonkeyCode free model access can draft that assertion list. Disclosure: This article was prepared as part of MonkeyCode's product outreach. Free model access does not choose the correct money rule.

You still own every expected total in the table. Paste the five-row table into the model prompt. Ask for a pytest loop that calls the existing wrapper.

Require the draft to import the current module path. Reject any assertion that changes twenty-nine to thirty. If the draft adds rows you did not write, delete those rows.

Run that draft on the free server option first. Keep the shared laptop tree untouched until the rows pass. The server is a clean checkout for this gate.

It is not a claim about hardware or uptime. Read the failure line before you edit production code. A mismatch on row one means the formula moved.

A mismatch on the printed line means the sink format moved. Those two mismatches belong in two different commits. A green draft is not a fairness proof.

python -m pytest tests/test_discount_rows.py -q --tb=short

6. Lock the pure function in a second commit

Add a direct call only after the wrapper rows pass. This check guards the extracted function from a later wrapper edit. It is optional, and it is not part of the extract commit.

from discount_legacy import discount_amount

def test_discount_amount_matches_row_one():
    assert discount_amount(199, "15", "50") == 29
    assert discount_amount(1000, "15", "50") == 50

Keep this file separate if review wants a small commit. The first commit proves the wrapper did not move. The second commit names the pure function as a stable seam.

Limits of the five rows

Five rows do not cover a non-integer rate string. Calling int on the text ten point five raises ValueError. That path stays unpinned until you add a row for it.

The tests use monkeypatch inside the test process. They do not model concurrent writers to the process environment. Do not cite this file as a concurrency proof.

The negative row preserves a quirk so the extract stays honest. Shipping that quirk to customers is a product decision. This gate does not make that product decision.

The plus-one probe is a local failure check only. It is not a benchmark against other tools. No timing numbers are claimed in this note.

No model quality score is claimed in this note. Free server access is an availability option for this workflow. Free model access is the other availability option.

They are not a promise of quota or duration. They also are not a named model build. If either option is unavailable, run the same pytest file locally.

Who should not use this gate

Skip it when this week's goal is to correct the money rule. Pinning twenty-nine would only delay the required fix. Write the new rule, then replace the row on purpose.

Skip it when the repo has no test runner. An extract without a failing probe is a guess. Guessing is how one-cent gaps land in review.

Skip it when the printed line is an unstable debug string. Pin the returned total and the dict fields instead. A noisy line will fail for reasons unrelated to money.

Skip it when subtotal is not an integer count of cents. This sample assumes integer cents and integer percent text. Decimal currency needs a different row set entirely.

It also needs a different pure function body. Do not reuse these five integers for decimal invoices. The gate would pin the wrong money unit.

Close this commit

Record the five discount rows before any move. Probe those rows with a plus-one formula next. Restore the floor rule after that probe ends.

Then extract one pure function and nothing else. Re-run the same file and stop there. Open a follow-up only for the rounding change you actually want.

That follow-up should show row one moving on purpose. The characterization commit should not contain that move. Use a free server checkout when the shared laptop tree cannot take the probe.

Pin Apply Order Before One Discount Extract

Dakota Huang — Fri, 09 Oct 2026 23:21:10 +0000

Pin apply order before you extract one discount rule. A free coding pass can draft the smallest patch. Frozen checks still decide whether that patch lands.

Messy carts hide tax, coupons, and warnings in one function. A wide extract often shifts cent totals or warning order. Green tests that never pinned those facts will miss it.

This workflow freezes three outputs, then allows one pure move. It fits a messy repo, not a greenfield design pass. Treat every code block below as a proposed, unexecuted example.

What must stay fixed

Keep the call order of coupon, tax, and shipping. Keep the integer cent total for each sample cart. Keep the warning lines, including their exact sequence.

Do not freeze private helper names in the first pass. Do not freeze incidental whitespace inside log text. Do not freeze comments or the order of locals.

Read the stop table first

Use this table before you accept any generated patch. Each row is a stop rule, not a style preference. If one row fails, drop the patch and retry smaller.

Signal	Keep	Reject
Stack order	coupon, then tax, then ship floor	tax moved ahead of the coupon
Cent total	same integer cents on each cart	float rounding or an off-by-one
Warning sequence	same lines, same order	a new line or a swapped pair
Diff width	one new function plus the call site	a second behavior edit in that patch
New dependency	none added	a network, clock, or env read

Step 1: Isolate the messy function

Start from one function that mutates a cart list. It applies a coupon, then tax, then a shipping floor. It also appends warnings while it walks the lines.

def apply_cart(lines, coupon_code, tax_bps):
    warnings = []
    total = 0
    for line in lines:
        cents = int(line['qty']) * int(line['unit_cents'])
        if coupon_code == 'SAVE10' and cents >= 1000:
            cents = cents - (cents // 10)
            warnings.append('coupon')
        tax = (cents * int(tax_bps)) // 10000
        cents = cents + tax
        if cents < 500:
            cents = 500
            warnings.append('ship_floor')
        line['cents'] = cents
        total += cents
    return {'total': total, 'warnings': warnings, 'lines': lines}

Label this block as the behavior you intend to keep. Do not clean it before the characterization tests exist. Cleaning first is how silent order bugs hide.

Step 2: Build three sample carts

Build three carts that stress three different branches. One cart should trigger the coupon and the tax path. One cart should miss the coupon and hit the floor.

One cart should stay above the floor with no coupon. Store expected totals as integers, never as floats. Store warnings as a list, not as a joined string.

Joined strings hide a swapped pair of warning lines. Integer cents remove binary float noise from the pin. Three carts are a floor, not full branch coverage.

Step 3: Write the characterization tests

Write one test per cart, and assert three facts. Assert the total, the warning list, and line cents. Leave helper names and formatting out of these assertions.

import copy
import pytest
from cart import apply_cart

CASES = [
    {
        'name': 'coupon_then_tax',
        'lines': [{'qty': 2, 'unit_cents': 800}],
        'coupon': 'SAVE10',
        'tax_bps': 500,
        'total': 1512,
        'warnings': ['coupon'],
        'line_cents': [1512],
    },
    {
        'name': 'floor_without_coupon',
        'lines': [{'qty': 1, 'unit_cents': 100}],
        'coupon': 'NONE',
        'tax_bps': 0,
        'total': 500,
        'warnings': ['ship_floor'],
        'line_cents': [500],
    },
    {
        'name': 'plain_above_floor',
        'lines': [{'qty': 1, 'unit_cents': 2000}],
        'coupon': 'NONE',
        'tax_bps': 250,
        'total': 2050,
        'warnings': [],
        'line_cents': [2050],
    },
]

@pytest.mark.parametrize('case', CASES, ids=lambda c: c['name'])
def test_apply_cart_pin(case):
    lines = copy.deepcopy(case['lines'])
    result = apply_cart(lines, case['coupon'], case['tax_bps'])
    assert result['total'] == case['total']
    assert result['warnings'] == case['warnings']
    assert [line['cents'] for line in result['lines']] == case['line_cents']

Step 4: Run the pin before any edit

Run the suite once and store the output beside the diff. A failing pin means the sample data, not the old code. Fix expected values only after you recheck the inputs.

pytest -q tests/test_apply_cart.py
git diff --stat -- cart.py tests/test_apply_cart.py

Treat a red pin as a data bug until inputs match. Do not change production code just to satisfy a bad sample. The old function is the oracle for this pass.

Step 5: Bound the smallest safe change

Ask for one extract, and name the forbidden edits. The new function may compute the coupon cents only. It must not read the clock, the env, or the network.

Pass the frozen tests and the stop table with that ask. Tell the assistant to return a patch, not a rewrite. Reject any reply that edits a second behavior.

Step 6: Use free model access after the pin

Disclosure: This article was prepared as part of MonkeyCode's product outreach. Use MonkeyCode free model access only after the pin is green. Use its free server so the suite stays off production hosts.

Those two options are availability claims, not a service contract. Do not assume a model name, quota, or hardware shape. Do not assume the free option will stay unchanged later.

Re-read the current product notes before you depend on either. Paste the function, the tests, and the stop table. Ask for the smallest patch that keeps every pin green.

Require the reply to leave warning order untouched. A useful prompt names the allowed move in one line. It also names files the patch must not touch.

Wide prompts produce wide diffs, even on a free model. A narrow prompt is part of the safety check.

Step 7: Review, then extract one pure rule

Review the diff before you run any new command. Check that only the coupon math moved out. Check that tax and the shipping floor still run in place.

def coupon_cents(cents, coupon_code):
    if coupon_code == 'SAVE10' and cents >= 1000:
        return cents - (cents // 10), 'coupon'
    return cents, None

def apply_cart(lines, coupon_code, tax_bps):
    warnings = []
    total = 0
    for line in lines:
        cents = int(line['qty']) * int(line['unit_cents'])
        cents, coupon_warning = coupon_cents(cents, coupon_code)
        if coupon_warning:
            warnings.append(coupon_warning)
        tax = (cents * int(tax_bps)) // 10000
        cents = cents + tax
        if cents < 500:
            cents = 500
            warnings.append('ship_floor')
        line['cents'] = cents
        total += cents
    return {'total': total, 'warnings': warnings, 'lines': lines}

This extract keeps the same integer math and the same warning text. It does not change when the coupon check runs. It is still a proposal until your suite passes on your machine.

Step 8: Rerun and measure the diff width

Apply the patch on a branch, then rerun the same suite. Compare the diff stat with your one-function budget. If the stat shows a second behavior file, stop and split the work.

git checkout -b pin-coupon-extract
pytest -q tests/test_apply_cart.py
git diff --stat HEAD

Use a tiny stat check so the file budget is executable. The script below is a proposal, not a shipped tool. It fails closed when the diff touches too many files.

import subprocess
import sys

def main():
    stat = subprocess.check_output(
        ['git', 'diff', '--stat', 'HEAD'], text=True
    )
    files = [line for line in stat.splitlines() if '|' in line]
    if len(files) > 2:
        print('reject: more than two files changed')
        return 1
    print('stat within file budget')
    return 0

if __name__ == '__main__':
    sys.exit(main())

If warnings move, revert and shrink the ask. If totals move, the extract is not safe yet. A green suite plus a narrow stat is the merge gate.

A free server is useful for this rerun, not for a deploy. Run the suite there, then bring back only the reviewed diff. Do not point that server at live customer data.

Limits of the pin

This pin does not prove tax law or coupon policy. It only proves the sampled carts stayed stable. Add a cart when you discover a new branch.

Nondeterministic clocks will make this kind of pin flap. Network reads will make the same pin flap too. Remove those reads before you trust a green run.

The free model can still misread integer division. The free server can still lack a test dependency. Neither limit is fixed here, because no quota or image is claimed.

The stat script can misread unusual file names in the diff. Treat it as a budget alarm, not a proof of safety.

Who should skip this flow

Skip this flow during an active production incident. Skip it when you cannot run the suite on the repo. Skip it when the change must alter totals on purpose.

Also skip it if no one can review the model diff. A free model can still propose a wide rewrite. Your review is the control, not a model score.

What this does not claim

Characterization tests come from established practice on legacy code. Michael Feathers documented this pin-before-edit habit for legacy code. The samples here are illustrative, not measured benchmark results.

No runtime, quota, or accuracy figure is claimed above. Verify current product notes before you treat access as stable. One green pin is not a license for a wide split.

Keep the next extract just as small as this one. Pin the next output before you move the next rule. If a free server is already available, rerun this suite there.

One Helper Moves Only After the Status Table Stays Green

Dakota Huang — Fri, 09 Oct 2026 19:57:15 +0000

One helper moves only after the status table stays green. A messy classifier mixes folding, alias lookup, and logging. Those three jobs should not move in one patch.

This workflow freezes observed outputs, then extracts one string helper. The helper must not change any pinned label. A later patch can fix quirks after the freeze holds.

The code below is an unexecuted teaching fixture for a scratch repo. It is not a claim about any live order system. Copy it, run it, and keep the results next to your diff.

The conclusion in one rule

Preserve today's outputs before you improve today's structure. Structure work is safe only when the table stays identical. Behavior work belongs in a separate, reviewed change.

That rule fits messy repositories with unclear ownership. It fits less well when the ticket demands a new label now. Read the skip section before you adopt the steps.

What the fixture actually does

The function classify_order accepts raw text and returns one label. A None input becomes an empty string before lookup. A known typo, the word payed, still returns paid.

Spaced input such as pa id returns review. That row is a quirk, not a target design. Empty input returns unknown, and other text returns pending.

Each call also appends a log line to a caller-supplied sink. The line stores the original text and the label. Tests assert both the label and that line.

The integer input stays in the table because callers may pass numbers. Removing that coercion is a behavior change, even if it looks cleaner. Leave it until a separate patch updates the expected row.

Fixture code

def classify_order(raw, sink):
    text = "" if raw is None else str(raw)
    folded = text.strip().lower()
    aliases = {
        "ok": "paid",
        "paid": "paid",
        "payed": "paid",
        "cancel": "cancelled",
        "canceled": "cancelled",
        "cancelled": "cancelled",
        "": "unknown",
    }
    if folded in aliases:
        label = aliases[folded]
    elif " " in folded and folded.replace(" ", "") in aliases:
        label = "review"
    else:
        label = "pending"
    sink.append(f"{text}|{label}")
    return label

Place the function in order_status.py before you write tests. Keep the alias literals inline for this first freeze. Moving the dictionary is a later cut, not this one.

Step 1. Execute rows before you write expectations

Run the function for a fixed input list and print both results. Record those prints as the golden table for this extract. Do not invent a row you have not executed.

Use this runner in the same scratch directory as the fixture.

from order_status import classify_order

def main():
    samples = [None, "", "  ", "paid", " payed ", "pa id", "CANCEL", "nope", 12]
    for raw in samples:
        sink = []
        label = classify_order(raw, sink)
        print(repr(raw), label, sink[0])

if __name__ == "__main__":
    main()

python status_probe.py

The probe is part of the method, not a benchmark harness. Save its printed output beside the test file. If a row surprises you, keep it until a later behavior patch.

Step 2. Turn the probe output into a table

input     label       log line           note
None      unknown     |unknown           None becomes empty text
""        unknown     |unknown           empty stays unknown
"  "      unknown     "  "|unknown       strip folds spaces to empty
paid      paid        paid|paid          direct alias
" payed " paid        " payed "|paid     typo and padding kept
pa id     review      pa id|review       internal space quirk
CANCEL    cancelled   CANCEL|cancelled   case fold only
nope      pending     nope|pending       fallback
12        pending     12|pending         non-string coerced

These nine rows are the contract for the next extract. The notes explain history, but assertions use only label and log line. A reviewer should be able to recompute every cell from the fixture.

Step 3. Lock the table in one test

import pytest
from order_status import classify_order

CASES = [
    (None, "unknown", "|unknown"),
    ("", "unknown", "|unknown"),
    ("  ", "unknown", "  |unknown"),
    ("paid", "paid", "paid|paid"),
    (" payed ", "paid", " payed |paid"),
    ("pa id", "review", "pa id|review"),
    ("CANCEL", "cancelled", "CANCEL|cancelled"),
    ("nope", "pending", "nope|pending"),
    (12, "pending", "12|pending"),
]

@pytest.mark.parametrize("raw,label,line", CASES)
def test_status_rows_stay_fixed(raw, label, line):
    sink = []
    assert classify_order(raw, sink) == label
    assert sink == [line]

The test module has one job: freeze current behavior. It does not document the ideal domain language. Add a comment that payed and review are preserved on purpose.

Install pytest in that environment before you record the baseline. A missing dependency is a harness failure, not a product failure. Fix the environment, then run the suite again.

Step 4. Record a baseline command

Run the same command you will use after the edit.

python -m pytest tests/test_order_status_rows.py -q

Expect nine passed tests before any production edit. Write that count in the pull request notes. A failed baseline means the harness is wrong, so fix the harness first.

Do not switch flags between the baseline run and the later run. A quieter flag or a new plugin can hide a real miss. Keep the working directory and Python environment fixed too.

Step 5. Score candidate cuts with a local rubric

Use a three-point rubric you can apply by reading the diff. Award one point for each extra function touched. Award one point if a golden label could change.

Award one point if logging text could change. These scores are a local rubric, not a measured field study. A lower score means a narrower change for this gate.

Candidate	Touch	Label risk	Log risk	Score	Gate
Extract fold_status only	1	0	0	1	allow
Extract alias dict only	1	1	0	2	defer
Extract fold and alias together	2	1	0	3	reject now
Delete the payed alias	1	1	1	3	reject
Replace review with paid	1	1	1	3	reject

Only a score of one may enter the current patch. The allowed cut creates fold_status and leaves lookup in the caller. That split is mechanical and easy to review.

The deferred cut moves policy, so it waits for its own tests. Deleting payed would change a pinned label and a log line. That deletion is a behavior patch, so the gate rejects it.

Step 6. Apply the single allowed extract

def fold_status(raw):
    text = "" if raw is None else str(raw)
    return text, text.strip().lower()

def classify_order(raw, sink):
    text, folded = fold_status(raw)
    aliases = {
        "ok": "paid",
        "paid": "paid",
        "payed": "paid",
        "cancel": "cancelled",
        "canceled": "cancelled",
        "cancelled": "cancelled",
        "": "unknown",
    }
    if folded in aliases:
        label = aliases[folded]
    elif " " in folded and folded.replace(" ", "") in aliases:
        label = "review"
    else:
        label = "pending"
    sink.append(f"{text}|{label}")
    return label

The helper returns original text and the folded key. The caller still owns every policy branch in this file. The log line still uses the original text, not the folded key.

Step 7. Re-run the baseline and stop on any miss

python -m pytest tests/test_order_status_rows.py -q

Require nine passed tests, matching the baseline note. If any row fails, revert the extract immediately. Do not edit an expected label to recover a green bar.

A green rerun means this structural move is safe to review. It does not mean the review quirk is acceptable forever. Schedule that correction as a behavior change with new tests.

Step 8. Optional draft from a free model

Disclosure: This article was prepared as part of MonkeyCode's product outreach.

MonkeyCode offers free model access and a free server option. Those two facts came from the operator for this draft. This article states no model names, quotas, hardware, or expiry.

Use the free model only as a patch drafter for the allowed cut. Paste the fixture, the test, and the rubric row you chose. Ask for fold_status and the matching caller change, nothing else.

Task: extract fold_status from classify_order.
Constraints: do not change labels, aliases, or log text.
Constraints: do not edit tests to make them pass.
Return: a unified diff for order_status.py only.

The free server option can execute the same pytest command. Use it when the laptop lacks the right interpreter. Do not treat a remote green run as proof about production data.

Review the diff before you trust the remote result. Reject any edits that land outside the order_status.py file. Reject any test change, alias deletion, or second helper.

If the draft is wider than the allowed cut, discard it. Ask again with the same constraints, or write the helper yourself. The table, not the draft, decides whether to merge.

Step 9. Accept the patch only after three checks

Count new functions, and allow only fold_status in this patch. Count changed files, and allow only the production module. Compare the alias literals with the parent revision.

A check fails if review disappears or payed changes meaning. A check fails if the log format drops the original text. Stop and revert the patch when any check fails.

Map the fixture onto a messy module

Start from one public function whose return value callers already depend on. Copy only synthetic inputs, or inputs your policy already allows in tests. Do not paste production payloads into the golden table.

Keep the file path stable while you extract the helper. A rename plus an extract hides the behavior diff. Land the rename only after this gate has passed.

Limits of the freeze

Characterization rows preserve defects until you change them on purpose. The payed alias and the review branch are current defects in this story. Shipping them longer is a product choice, not a testing victory.

A nine-row table can still miss rare inputs. Numbers other than twelve, bytes, and custom objects stay untested here. Expand the table only by executing new rows, then freezing them.

The free server may differ in Python version, locale, or installed plugins. Pin the test command in the patch notes so reviewers can repeat it. Do not upload secrets, customer orders, or private repository tokens.

A model can pass tests while making the code harder to read. Reject clever rewrites that hide the alias table. The goal is a smaller, reviewable diff, not a shorter file at any cost.

Who should skip this workflow

Skip it when the ticket requires a new label in the same change. Write the new expected rows first, then change the mapping. Calling that mix a pure extract will mislead reviewers.

Skip it when the entry point cannot run without production credentials. A borrowed database row is not a characterization fixture. Build a local input list, or do not claim the freeze is real.

Skip it for new code that has no callers and no current outputs. Ordinary unit tests should state the intended contract directly. There is nothing old to preserve in that case.

Skip it if your review policy forbids locking known defects even briefly. Some teams require the typo fix in the same pull request. Follow that policy instead of forcing this gate.

Commit order

Make the first commit contain only the golden test and the probe. Production behavior should be unchanged in that commit. Reviewers can run pytest before they read any move.

Make the second commit contain only fold_status and its call. The expected table must stay byte-for-byte stable across commits. Mention the baseline count in the commit message.

Leave alias cleanup, review-label redesign, and logger replacement for later commits. Each of those can change a pinned row. Each one needs its own test update before the code change.

After the gate

If you already use MonkeyCode, point the free model at this frozen suite. Keep the merge decision on the same nine passing tests.

Invoice Cents Stay Put While One Lookup Moves

Dakota Huang — Fri, 09 Oct 2026 16:46:03 +0000

Frozen invoice cents should block a wide rewrite.
Pin money, receipt text, and the audit row before any split.
Then move only the tier-rate lookup and leave the boundary quirk.

The cut this note allows

build_invoice currently chooses a rate, formats text, and appends audit data.
Those three jobs should not move in one diff.
This cut moves the rate lookup and nothing else.

Sample limits

The listing is a scratch module for a local refactor drill.
It uses integer cents so totals do not depend on binary floats.
It is not a tax engine, and the rates are fixtures only.

Use Python 3 with pytest installed in that same environment.
No third-party billing library is required for this drill.
Treat the listings as an unexecuted drill, not a measured benchmark.

Boundary quirk to lock

A subtotal of 10000 cents stays on the zero rate.
The boundary check uses greater than, not greater or equal.
Do not correct that comparison inside this extract.

Michael Feathers named this pinning style characterization testing in 2004.
The source book is Working Effectively with Legacy Code.
The rows below apply that idea to one invoice function.

Contract table

Contract	What the test reads	Allowed in this cut
Money	discount_cents and total_cents	No change
Text	exact receipt string	No change
Audit	one appended dict	No change
Input	order dict equality after the call	No change
Lookup	rate branches moved into `tier_rate`	Move only

Use that table as the review checklist before editing.
A green money test is not enough if text moved.
Reject the diff when any forbidden cell changes.

Step 1: Save the mixed function

Put this file at invoice.py before you run tests.
Keep the name stable so the import in the test file resolves.

def build_invoice(order, audit):
    subtotal = order["subtotal_cents"]
    tier = order["tier"]
    if tier == "gold" and subtotal > 10000:
        rate = 1500
    elif tier == "silver" and subtotal > 10000:
        rate = 800
    else:
        rate = 0
    discount = (subtotal * rate) // 10000
    total = subtotal - discount
    receipt = (
        f"tier={tier}\n"
        f"subtotal_cents={subtotal}\n"
        f"discount_cents={discount}\n"
        f"total_cents={total}\n"
    )
    audit.append({
        "tier": tier,
        "subtotal_cents": subtotal,
        "rate_bps": rate,
        "discount_cents": discount,
        "total_cents": total,
    })
    return {
        "receipt": receipt,
        "discount_cents": discount,
        "total_cents": total,
    }

This module still mixes lookup, text, and audit writes.
The rate branches sit inside build_invoice on purpose.
The next steps move those branches and nothing more.

Step 2: Add the characterization file

Save the rows below as test_invoice.py beside the module.
Each row locks money, text, audit, and input identity.
The last assert checks that the order dict stays unchanged.

import pytest
from invoice import build_invoice

CASES = [
    ("gold", 10000, 0, 10000, 0),
    ("gold", 10001, 1500, 8501, 1500),
    ("silver", 10000, 0, 10000, 0),
    ("silver", 20000, 1600, 18400, 800),
    ("bronze", 8000, 0, 8000, 0),
]

@pytest.mark.parametrize(
    "tier,subtotal,discount,total,rate",
    CASES,
)
def test_invoice_contracts(tier, subtotal, discount, total, rate):
    order = {"tier": tier, "subtotal_cents": subtotal}
    audit = []
    result = build_invoice(order, audit)
    receipt = (
        f"tier={tier}\n"
        f"subtotal_cents={subtotal}\n"
        f"discount_cents={discount}\n"
        f"total_cents={total}\n"
    )
    assert result["discount_cents"] == discount
    assert result["total_cents"] == total
    assert result["receipt"] == receipt
    assert audit == [{
        "tier": tier,
        "subtotal_cents": subtotal,
        "rate_bps": rate,
        "discount_cents": discount,
        "total_cents": total,
    }]
    assert order == {"tier": tier, "subtotal_cents": subtotal}

A helper extract must not start writing back into that dict.
Five cases cover the boundary, both paid tiers, and bronze.
Gold at 10001 cents floors the leftover basis points away.

That remainder drop is current behavior, so the row keeps it.
Silver at 20000 cents divides evenly, which gives a control row.
Bronze never selects a paid rate, which locks the else branch.

Step 3: Run the gate before editing

Run the characterization file before you open a diff.
Use the quiet pytest flag so the pass count stays visible.
Run both commands from the directory that holds the two files.

python -m pytest -q test_invoice.py

Expect five passed tests and zero failures at this point.
If a row fails, correct the expected fixture first.
Do not edit production code to satisfy a guessed total.

Record the pass count in the commit message.
Keep that note next to the later diff stat.
Reviewers can then see the gate was green first.

Commit the green gate before you move any branch.
Use a message that records the five passing rows.
Run the init command only when the folder has no repository yet.

git init
git add invoice.py test_invoice.py
git commit -m "Pin four invoice contracts before one lookup move"

Step 4: Move only the lookup

After the gate is green, move the rate branches out.
Place them in a new tier_rate helper with the same comparisons.
Call that helper from build_invoice with the same arguments.

def tier_rate(tier, subtotal):
    if tier == "gold" and subtotal > 10000:
        return 1500
    if tier == "silver" and subtotal > 10000:
        return 800
    return 0

Do not rename keys, and do not edit the receipt template.
Keep the floor division in the caller for this cut.
Floor division is part of the money contract, so leave it there.

Step 5: Re-run and read the diff

Re-run the same pytest command after the helper move.
Then inspect the git diff for invoice.py only.
Initialize a git repo first if this folder is not one yet.

python -m pytest -q test_invoice.py
git diff --stat -- invoice.py
git diff -- invoice.py

The diff should add tier_rate and one call site.
Receipt lines and audit keys should stay out of the hunk.
Stop if unrelated lines appear in that diff.

Step 6: Apply the reject list

Reject the patch when any listed item appears.
A changed comparison operator at the 10000 boundary is a reject.
A switch from floor division to round is a reject.

A new blank line inside the receipt string is a reject.
An audit key rename is a reject even if values match.
A write back into the order dict is a reject.

Each rejected item becomes a separate follow-up ticket.
This cut chooses no behavior change at all.
Update expected rows only when a later ticket changes money.

Worked numbers for the boundary rows

Gold at 10000 cents takes the zero rate.
The comparison fails, so the lookup returns 0 basis points.
Discount cents are the floored product, which equals 0 here.

Total cents stay at 10000, and the receipt prints that pair.
The audit dict stores rate_bps 0 beside those same totals.
Input equality still holds because the function only reads the order.

Gold at 10001 cents takes 1500 basis points.
The product of 10001 and 1500 equals 15001500.
Floor division by 10000 yields 1500 discount cents.

The leftover 1500 in that product is discarded.
Total cents become 8501, and every contract stores that result.
Silver at 20000 cents takes 800 basis points with no remainder.

The silver product of 20000 and 800 equals 16000000.
Floor division by 10000 yields 1600 discount cents.
Total cents become 18400, which gives the even control case.

Bronze at 8000 cents stays on the zero rate path.
These traces are the numeric baseline for the review.
If a draft changes one printed integer, the test fails.

That failure is the signal to revert, not to retune the row.
Do not edit an expected total just to keep a wide diff.
The row changes only when the ticket asks for new money.

Where a free draft can sit

A coding model may draft the helper move after the gate is green.
Disclosure: This article was prepared as part of MonkeyCode's product outreach.
MonkeyCode provides free model access and a free server option.

Those two facts are the only product claims used here.
Paste both Python files and request one lookup extract.
Tell the model to leave receipt text and audit keys untouched.

Treat the reply as an untrusted diff, not a passing run.
Apply it on the free server if you want a disposable workspace.
Run the same pytest command before you accept the hunk.

The free server does not replace the characterization gate.
This note does not state quotas, hardware, or plan duration.
If those terms matter, read the current product docs first.

If a free session is already open, use that scratch pad for the extract.
Keep the pytest gate as the only merge check.

Limits of these five rows

Five rows do not cover negative cents or missing keys.
Those paths can still raise, and this suite stays green.
Add an error-contract test before you touch exception text.

The suite locks today's floor division, including the dropped remainder.
A product owner may want half-up rounding in a later ticket.
That ticket needs new expected rows before the rate edit.

Integer cents remove binary float noise from this drill.
A live checkout may still need currency rules omitted here.
Do not copy these fixture rates into production billing.

A fresh git commit needs a local user name and email already set.
This drill does not walk through git identity setup.

Who should skip this drill

Skip this drill when no caller depends on current output.
A prototype that changes daily will thrash these fixtures.
Wait until one consumer treats the rows as a contract.

Skip this drill when the next change must alter money.
Write the new expected totals before you edit the rate table.
A frozen characterization file would block that intended fix.

Skip this drill if pytest cannot run in the target repo.
A paper diff with no command output is not this gate.
Also skip generated files that your team does not own.

What the gate decides

The safe extract is the lookup, not the whole invoice function.
Money, text, audit, and input identity decide the merge.
A model draft stays optional, and the frozen rows stay in charge.

A Two-Commit Gate for a Messy Batch Module

Dakota Huang — Fri, 09 Oct 2026 15:42:40 +0000

A messy module should change only after today's outputs are frozen. A coding model may draft that freeze in a scratch repo. It should not ship a wide rewrite in the same commit.

Core conclusion

Land characterization tests before any production edit lands. Extract one pure function in the next commit. Reject the patch when production lines outgrow the test diff.

Why this gate exists

Wide cleanups mix renames with real behavior changes. A quiet print tweak can break downstream parsers. Review time then goes to style, not to locked outputs.

Side effects hide inside helper functions that look pure. Directory lists, file writes, and clocks are observations. Each one needs a golden assertion before a move.

Proposed fixture

The module below is an unexecuted proposal for a scratch repo. It is not a log from a real service. Paste it only where you can delete the tree.

# proposal: batch_roll.py — unexecuted example
import json
import os
import time
from pathlib import Path

def run(src, dst, now=None):
    now = now or time.time()
    rows = []
    for name in sorted(os.listdir(src)):
        path = Path(src) / name
        if path.suffix != ".json":
            continue
        data = json.loads(path.read_text())
        status = "late" if data.get("due", now) < now else "open"
        rows.append({"id": data["id"], "status": status, "name": name})
        out = Path(dst) / (data["id"] + ".out")
        out.write_text(status + "\n")
    print(len(rows))
    return rows

Four jobs currently share this one function in the sample. It filters names, classifies due times, writes files, and prints a count. That mix is the reason the gate exists.

Observations to freeze

Freeze public outputs rather than private variable names. Local names can change without changing external behavior. Bytes, exit paths, and prints cannot move silently.

Non-JSON files must never create an output file. A due value below now yields late, and every other due stays open.

Each id writes an out file containing the status and a newline. The printed integer must equal the number of accepted rows.

Missing keys should stay as today's crash until a later bugfix. Do not improve KeyError handling during an extract commit. A new error type is a behavior change.

Side-effect map

Map each side effect to the test that locks it. Unmapped side effects stay out of scope for this extract. Add a new row before you move that line.

Side effect	Lock in the test	Extract commit
`print(len(rows))`	captured stdout is `2\n`	not allowed
`write_text(status)`	`a.out` and `b.out` bytes	not allowed
suffix filter on `listdir`	`notes.out` is absent	not allowed
`due` compared with `now`	row `status` fields	allowed via `classify`
`time.time()` default	test passes `now=200`	not allowed

Review table

Apply this table before you merge any model patch. Read each row as a hard reject rule for this pass.

Patch shape	Tests already green	Production edit	Decision
Tests only	this commit	none	land
Tests plus comments	this commit	comments only	reject
One pure extract	previous commit	smaller than test diff	review
Extract plus print change	any	any	reject
Extract plus path change	any	any	reject
Clock read moved into helper	any	any	reject
Assertions edited to match model	any	any	reject

This table is a review rule for humans. It is not a model score and not a timing result. No pass rate is claimed for any vendor.

1. Create a disposable tree

Work only inside a directory you can delete. Do not point these commands at a shared checkout. The steps are a proposed workflow, not a recorded run.

mkdir -p scratch_gate/src scratch_gate/tests
cd scratch_gate
python -m venv .venv
. .venv/bin/activate
python -m pip install pytest

Keep the virtualenv inside the disposable scratch tree. That choice avoids touching a global interpreter install. Commit neither the virtualenv nor real customer files.

2. Plant inputs with a pinned clock

Pin now at 200 so status does not depend on the wall clock. File a is late because its due value is below two hundred. File b stays open because 300 is not less than 200.

mkdir -p src
printf '%s\n' '{"id":"a","due":100}' > src/a.json
printf '%s\n' '{"id":"b","due":300}' > src/b.json
printf '%s\n' 'not-json' > src/notes.txt

Sorted names matter because listdir order is not your contract. The test should assert the returned list order explicitly. If sort order is accidental, say so in the test name.

3. Add the characterization test

Add one test that locks files, rows, and the printed count. Keep the test free of network calls and of sleeps. Label the file as a proposal until you execute it.

# proposal: tests/test_batch_roll.py — unexecuted example
import batch_roll

def test_freeze_files_status_and_print(tmp_path, capsys):
    src = tmp_path / "src"
    dst = tmp_path / "dst"
    src.mkdir()
    dst.mkdir()
    (src / "a.json").write_text('{"id":"a","due":100}\n')
    (src / "b.json").write_text('{"id":"b","due":300}\n')
    (src / "notes.txt").write_text("not-json\n")

    rows = batch_roll.run(src, dst, now=200)
    printed = capsys.readouterr().out

    assert rows == [
        {"id": "a", "status": "late", "name": "a.json"},
        {"id": "b", "status": "open", "name": "b.json"},
    ]
    assert (dst / "a.out").read_text() == "late\n"
    assert (dst / "b.out").read_text() == "open\n"
    assert not (dst / "notes.out").exists()
    assert printed == "2\n"

The test uses tmp_path so writes stay inside pytest. It passes now so the clock is not read. It captures stdout so a print change fails.

Place batch_roll.py at the scratch repo root before pytest. Pytest imports that module from the current working directory. A package layout needs pythonpath, which this scratch tree skips.

4. Commit tests with a clean production tree

Run the new test before you invite a wider edit. The first commit should contain tests and fixtures only. A production diff in this commit fails the gate.

python -m pytest -q tests/test_batch_roll.py
git add tests/test_batch_roll.py
git commit -m "test: freeze batch_roll outputs"
git show --stat --name-only HEAD

If a model already edited batch_roll.py, restore that file. Then commit the characterization test without that file. Do not squash these two intentions into one later.

git restore --source=HEAD -- batch_roll.py

git restore needs a committed baseline for that path. If the file is still untracked, leave it untouched. The point of this step is a test-only commit.

5. Allow one pure extract

The smallest safe change is a classifier with two arguments. It returns late or open and performs no I/O. The caller still owns prints, writes, and directory reads.

# proposal: smallest extract — unexecuted
def classify(due, now):
    if due < now:
        return "late"
    return "open"

Replace only the inline status expression with a call. Pass the same now value the test already pins. Do not add a default clock read inside classify.

# proposal: call site — unexecuted
status = classify(data.get("due", now), now)

That one line is the whole production behavior change. If the patch adds helpers for paths, reject it. Path policy belongs in a later gated commit.

6. Score the second diff

Re-run the same test file with no assertion edits. Then compare production line changes with the test commit size. Accept only when production stays smaller and tests stay identical.

python -m pytest -q tests/test_batch_roll.py
git diff --numstat -- batch_roll.py
git diff --numstat -- tests/test_batch_roll.py

A zero on the test numstat means assertions did not move. A non-zero test numstat means the model rewrote the freeze. Revert the production file and keep the original test.

# proposal: score_gate.py — unexecuted checker
def allow_extract(prod_lines, prior_test_lines, assertions_changed, test_lines_now):
    if assertions_changed or test_lines_now != 0:
        return False
    if prod_lines <= 0:
        return False
    return prod_lines < prior_test_lines

The checker compares production lines with the prior test commit. A larger production diff fails even when pytest is green. Run the function on your numstat values before you merge.

An illustrative split is thirty test lines and eight production lines. That ratio is an example budget, not a measured result. Replace the numbers with your own git numstat output.

7. Failure cases to reject

A patch that formats JSON while extracting classify fails the gate. Formatting is a second behavior, even if tests still pass. Add a byte-level fixture before you allow a formatter.

A patch that swaps print for a logger fails the gate. The frozen stream is part of the contract for this pass. Logging policy can be its own later commit.

A patch that catches KeyError fails the gate. Today's crash is frozen until you schedule a bugfix. Write the new exception test in a separate commit first.

Where free model access fits

The gate stands if you draft every line yourself. A coding model is optional labor, not the source of truth. You still own the commit split and the revert.

Disclosure: This article was prepared as part of MonkeyCode's product outreach. MonkeyCode offers free model access and a free server option. Those are the only product facts used here.

This article states no model name, quota, hardware shape, or time limit. Use the free model access to draft the test and the one extract. Use the free server option to run the draft off a work laptop.

This article claims no isolation guarantee for that server. Treat the server as convenience, not as a security boundary. Do not upload secrets just because the option is free.

Paste the proposal function, not live customer files. Keep tokens, keys, and private paths out of the prompt. Run pytest only on fixtures you just created locally.

If that free access is already available, try this split. Use a scratch tree and wait for the review table. Keep the merge until the table says review or land.

Limits

Golden tests preserve bugs as well as features. A wrong late label becomes the new contract. Schedule behavior fixes in a later commit with a stated reason.

tmp_path does not match production permissions or mounts. A green local run can still fail on a read-only volume. Copy one real directory into a sandbox before release.

Pinned integers hide string dates and time zones. If real files store due as text, this fixture is too kind. Capture one redacted real shape before you trust classify.

No runtime numbers are reported because this draft was not executed. Your machine, your pytest, and your data will differ. Treat every command as a template to run locally.

Who should skip it

Skip the gate when the script has no stable output yet. Exploratory notebooks need a written spec before golden files. Freezing that churn would only lock noise in place.

Skip it when the task is an intentional behavior change. Put the new expected bytes in their own commit first. Then change production to match that new freeze.

Skip it during an active security incident that must change failures now. A locked bug is the wrong priority in that window. Patch the incident first, then rebuild the freeze later.

Skip it if you lack a disposable copy of the repo. Models can widen a diff faster than you can read it. Use a disposable clone or do not start.

Close

Freeze files, status, and prints in one commit. Extract one pure function in the next commit. Reject every patch that moves a second side effect.

Seal File, Clock, and Print Before One Module Split

Dakota Huang — Fri, 09 Oct 2026 12:32:20 +0000

Split a god module only after tests seal current behavior. Pin files, clocks, prints, and errors before any move. Then extract one pure function and stop there.

Why unsealed splits drift

A wide module hides parse, math, and disk writes together. A quick extract often changes paths, times, or blank lines. Those diffs look tiny and still break callers.

Reviewers cannot separate a safe move from a contract change. Characterization tests record what the code does today. They do not claim that behavior is the right product.

The only change this pass allows

This pass may move one function boundary in one file. Inputs stay identical, and output bytes stay stable. Clocks, prints, and file writes remain in the caller.

Do not rename public functions in the same commit. Do not add a dependency to clean up formatting. Do not fix a known bug until the seal is green.

What to pin, leave, or block

Use this table before you touch the module. A blocked row means the split is not the smallest safe change.

Observed signal	Pin now	Leave alone	Block the split
Summary file bytes	Yes
Printed status line	Yes
Return value	Yes
Exception type on a bad row	Yes
File absent after a bad row	Yes
Helper names inside the file		Yes
Comment text		Yes
New third-party package			Yes
Clock read moved into the helper			Yes
Path built from cwd inside the helper			Yes

Step 1: Keep the messy module unchanged

Treat the file below as the current production shape. It is a proposed example, not a measured repo result. Do not improve it before the tests exist.

import datetime
from pathlib import Path

def run_job(source_text, dest_path):
    rows = []
    for line in source_text.splitlines():
        if not line.strip():
            continue
        name, qty, price = line.split(",")
        rows.append((name.strip(), int(qty), float(price)))
    total = 0.0
    lines = []
    for name, qty, price in rows:
        amount = qty * price
        total += amount
        lines.append(f"{name}:{amount:.2f}")
    stamp = datetime.datetime.now().strftime("%Y-%m-%d")
    body = "\n".join(lines + [f"TOTAL:{total:.2f}", stamp])
    Path(dest_path).write_text(body + "\n", encoding="utf-8")
    print(f"wrote {len(rows)} rows")
    return total

Three side effects sit beside the row math. The clock is local and the print uses stdout. The write uses only the destination path given.

Step 2: Seal the happy path

Put the test next to the module in a fresh tree. Freeze the date so a laptop clock cannot change the file. Assert bytes, return value, and the exact print.

import datetime as dt

import job_report

class FrozenDate(dt.datetime):
    @classmethod
    def now(cls, tz=None):
        return cls(2026, 10, 9)

def _freeze(monkeypatch):
    monkeypatch.setattr(job_report.datetime, "datetime", FrozenDate)

def test_happy_path_seals_bytes_and_print(tmp_path, capsys, monkeypatch):
    _freeze(monkeypatch)
    dest = tmp_path / "out.txt"
    source = "Ada, 2, 3.5\n\nBea, 1, 4\n"
    total = job_report.run_job(source, dest)
    assert total == 11.0
    assert capsys.readouterr().out == "wrote 2 rows\n"
    assert dest.read_text(encoding="utf-8") == (
        "Ada:7.00\nBea:4.00\nTOTAL:11.00\n2026-10-09\n"
    )

The fixture date is a lock, not a news claim. The token 2026-10-09 is the review date for this draft. Change it only if your sealed sample used another day.

Step 3: Seal the empty path and the bad row

Empty input still writes a total line and a stamp. A bad quantity raises ValueError before any write. Import pytest before you add the two tests below.

import pytest

def test_blank_lines_only_write_zero_total(tmp_path, capsys, monkeypatch):
    _freeze(monkeypatch)
    dest = tmp_path / "out.txt"
    total = job_report.run_job("\n  \n", dest)
    assert total == 0.0
    assert capsys.readouterr().out == "wrote 0 rows\n"
    assert dest.read_text(encoding="utf-8") == "TOTAL:0.00\n2026-10-09\n"

def test_bad_qty_raises_and_skips_the_file(tmp_path, monkeypatch):
    _freeze(monkeypatch)
    dest = tmp_path / "out.txt"
    with pytest.raises(ValueError):
        job_report.run_job("Ada, x, 3\n", dest)
    assert dest.exists() is False

Both facts are current behavior, even if a later ticket changes them. Do not assert a friendlier error message in this pass. Record the exception type the module raises today.

Step 4: Run the suite on a clean tree

Run these commands from a new virtual environment. They are the proposed workflow, not a published benchmark. Stop if the seal is red, and do not edit production code yet.

python -m venv .venv
source .venv/bin/activate
python -m pip install pytest
python -m pytest tests/test_job_report.py -q

On Windows, use the Scripts activate script instead. Keep the same pytest invocation after that activation. A green run means the seal matches this tree only.

Commit the tests alone if history allows a test-only commit. The next commit may contain only the extract. Two commits make a reverted move easy to see.

Step 5: Extract one pure function

After the seal is green, move only the row math. Leave parsing, the clock, the print, and the write in run_job. The public signature stays run_job with source text and dest path.

def summarize_rows(rows):
    total = 0.0
    lines = []
    for name, qty, price in rows:
        amount = qty * price
        total += amount
        lines.append(f"{name}:{amount:.2f}")
    return lines, total

def run_job(source_text, dest_path):
    rows = []
    for line in source_text.splitlines():
        if not line.strip():
            continue
        name, qty, price = line.split(",")
        rows.append((name.strip(), int(qty), float(price)))
    lines, total = summarize_rows(rows)
    stamp = datetime.datetime.now().strftime("%Y-%m-%d")
    body = "\n".join(lines + [f"TOTAL:{total:.2f}", stamp])
    Path(dest_path).write_text(body + "\n", encoding="utf-8")
    print(f"wrote {len(rows)} rows")
    return total

Re-run the same pytest command with no test edits. A failure means the extract changed a sealed output. Revert the helper and try a smaller move.

Step 6: Reject diffs that fail the table

Read the diff before you trust the green suite. A green suite can miss a new import or a moved clock. Use the block column as a hard stop.

Reject the change if summarize_rows calls datetime or print. Reject it if the helper opens dest_path or reads the working directory. Reject a format tweak, even when the tests still pass by luck.

Add a direct unit check only after the seal stays green. That check may call summarize_rows with in-memory tuples. It must not replace the file and print seals.

def test_summarize_rows_is_pure_math():
    lines, total = job_report.summarize_rows([("Ada", 2, 3.5)])
    assert lines == ["Ada:7.00"]
    assert total == 7.0

This extra test is optional and stays local. Skip it if the extract is not in the tree yet. Do not let it become the only proof.

Where draft help and a remote run fit

A human still owns every sealed assertion here. A model can propose extra cases from the current file. Accept a case only when it matches observed output.

Disclosure: This article was prepared as part of MonkeyCode's product outreach. MonkeyCode's free model access can draft those candidate cases. Its free server option can run the same pytest command.

That split keeps a laptop clock and a home path out of the baseline. Do not treat a drafted assertion as a specification. Compare each expected string with a local run first.

If the server path differs, keep tmp_path and avoid a home directory. Check MonkeyCode's free server option if a remote baseline helps.

Limits of this seal

The seal preserves bugs as well as useful contracts. A wrong total stays wrong until a later separate change. Say that clearly in the pull request body.

Patching datetime depends on the import style in the module. This example patches import datetime, as written above. A from-import style needs a different patch target.

These tests do not cover concurrent writers or partial disk failures. They also skip encoding errors from the destination filesystem. Add those only if production already depends on them.

A free model draft may fix the bad-row path while sealing it. That is a failed draft, not a better refactor. Delete any assertion the current module does not already satisfy.

Two-decimal formatting can hide binary float noise later. Pick sample prices that land on exact tenths.

A hosted runner is not a permanence promise or hardware claim. Confirm current access in the product before you rely on it.

Who should not use this pass

Skip this pass if the ticket requires a behavior change now. Write the new contract test first, then change code. Do not freeze a bug you must remove in the same commit.

Skip it when the module calls production networks or reads real secrets. A characterization run would repeat that side effect. Isolate or replace that call before you record outputs.

Skip it if nobody can run the suite before merge. An unread model draft is not a seal. Also skip it when the next change must cross several packages at once.

Close on the commit boundary

Green tests plus a one-function diff is the exit bar. If the diff also moves the clock, the pass is not done. Revert the diff, reseal the outputs, and extract less.

Pin the Golden Row Before You Split Dispatch

Dakota Huang — Fri, 09 Oct 2026 08:42:04 +0000

A messy refactor fails when the new shape changes hidden behavior. Characterization tests record current outputs before any structural move. The smallest safe change then moves one pure decision only.

Do not ask a model to invent the expected row. Capture one real call, then lock that captured row. A later split stays safe only when that row still matches.

The module under change

The sample module is one notification dispatcher function. It filters recipients, renders a body, and calls send. Those three jobs share one mutable result list.

Treat the listing as a proposed teaching fixture. It was not executed against a live mailbox or vendor API. Use fake addresses and keep customer payloads off the model.

def dispatch(events, transport, template):
    sent = []
    for event in events:
        if event.get("status") != "ready":
            continue
        if not event.get("email"):
            continue
        body = template.format(name=event["name"], code=event["code"])
        transport.send(event["email"], body)
        sent.append({"email": event["email"], "body": body})
    return sent

What must stay fixed

Freeze the skip rules before you touch the function shape. A missing status and a blank email must still drop the row. Rendered body text and send order must stay identical.

The extract target is the eligibility predicate alone. Transport calls and template strings stay in the original function. That boundary keeps the first diff small and reviewable.

Decision table

Read the table before you write the first assertion. Rows marked freeze are the characterization targets for this pass. The single change row is the predicate extraction.

Check	Current result	This pass
status is not ready	row skipped	freeze
email is blank	row skipped	freeze
body equals template output	exact string	freeze
send order	input order of kept rows	freeze
eligibility predicate	inline in the loop	extract
transport implementation	injected fake in tests	freeze
template wording	unchanged format string	freeze

Workflow

Follow the six steps in order on one function only. Stop after the golden row passes on the extracted predicate.

1. Capture one golden call

Start from a known input list with three events. One event is ready, one lacks status, and one lacks email. Record the returned list, not a guessed ideal list.

Store that record in a fixture file next to the test. Commit the fixture with the test in the same change. A missing fixture means the characterization step is incomplete.

EVENTS = [
    {"status": "ready", "email": "a@example.test", "name": "Ada", "code": "14"},
    {"status": "hold", "email": "b@example.test", "name": "Bea", "code": "15"},
    {"status": "ready", "email": "", "name": "Cam", "code": "16"},
]
TEMPLATE = "Hello {name}, code {code}"

Paste the function output into a JSON fixture after one local run. That file becomes the only expected value for this pass. Do not hand-edit the body string to look cleaner.

2. Lock the current function

The test calls the public function through a fake transport. The fake records address and body in call order. The assertion compares both the return value and the fake log.

import json
from pathlib import Path

class FakeTransport:
    def __init__(self):
        self.calls = []

    def send(self, email, body):
        self.calls.append({"email": email, "body": body})

def test_dispatch_matches_golden_row():
    fixture = json.loads(Path("tests/fixtures/dispatch_golden.json").read_text())
    transport = FakeTransport()
    sent = dispatch(fixture["events"], transport, fixture["template"])
    assert sent == fixture["sent"]
    assert transport.calls == fixture["calls"]

Keep each assertion literal, narrow, and tied to the fixture. Do not add new product rules inside this test. A characterization test documents behavior, including current bugs.

3. Run the suite on a clean tree

Local site-packages can hide an import-time side effect. Run the same test from a clean checkout before any logic edit. Record the language pin in the test notes before that run.

Disclosure: This article was prepared as part of MonkeyCode's product outreach. The operator reports free model access and a free server option. This note adds no quotas, hardware, model names, or duration.

Use that free server as a second execution seat only. It is not a production replica unless you proved the match. If the language pin is unknown, stop and record it first.

python -m venv .venv
.venv/bin/python -m pip install pytest
.venv/bin/python -m pytest tests/test_dispatch_golden.py -q

Treat those commands as a proposed sequence for a Unix shell. Windows paths still need the matching venv layout here. The goal is one clean interpreter, not a tuned benchmark.

4. Let the model draft the harness

A free coding model can draft the fake transport class. Paste the captured fixture and ask for a loader only. Reject any draft that writes an expected value from memory.

Review the diff as if a junior teammate wrote it. Delete unused helpers before you run the suite. The model remains a drafter, not the behavior authority.

Give the model this constraint in the prompt text. "Copy expected JSON from the fixture file I pasted." "Do not invent emails, bodies, or status rules."

Those two lines cut a common failure mode. Keep both lines in the prompt until the diff is clean.

5. Make the smallest cut

Extract a function named eligible that returns a boolean. Move only the status check and the email check. Leave rendering and the transport send call inside dispatch.

def eligible(event):
    if event.get("status") != "ready":
        return False
    if not event.get("email"):
        return False
    return True

def dispatch(events, transport, template):
    sent = []
    for event in events:
        if not eligible(event):
            continue
        body = template.format(name=event["name"], code=event["code"])
        transport.send(event["email"], body)
        sent.append({"email": event["email"], "body": body})
    return sent

Preserve iteration order and the result append order. Do not rename keys while you extract the predicate. A rename is a second change and needs its own test.

6. Re-run the same golden row

Run the characterization test again after the extract. The fixture must match with zero edits to expected text. If it fails, revert the extract before you widen the test.

Add one direct unit test for eligible after the green run. That new test may cover edges the golden row skipped. It must not replace the original characterization test.

def test_eligible_rejects_hold_and_blank_email():
    assert eligible({"status": "hold", "email": "b@example.test"}) is False
    assert eligible({"status": "ready", "email": ""}) is False
    assert eligible({"status": "ready", "email": "a@example.test"}) is True

Failure checks before a second edit

A red test after the extract has three common causes. The predicate dropped a key check from the original branch. The loop skipped an append that used to happen.

A third cause is a model edit outside the allowed function. Inspect the diff and revert every unrelated line. Then rerun the golden row before any new design talk.

git diff -- tests/test_dispatch_golden.py dispatch.py
git checkout -- dispatch.py
.venv/bin/python -m pytest tests/test_dispatch_golden.py -q

Use the checkout command only when the extract itself is the suspect. Do not discard a fixture you already captured and reviewed. The golden file stays put while the logic change goes back.

Limitations you should state in the review

This method freezes current behavior, including known defects. If the current skip rule is wrong, do not lock it. Write a failing specification test and fix that rule first.

A free server is not automatically a production replica. Locale, timezone, and package pins can still diverge. Treat a remote green bar as extra evidence, not proof.

Free model access does not make the oracle correct. The model can still invent fields that the fixture lacks. Human review of every expected value remains mandatory.

This walkthrough reports no latency numbers and no pass rates. It also reports no hardware size and no retention window. Do not cite it as a benchmark of any coding model.

Who should skip this path

Skip this path when a production hotfix cannot wait. Skip it when fixtures would contain secrets or customer rows. Skip it when you cannot run tests on a clean tree.

Skip it when the bug is the behavior you would freeze. Skip it when the change must alter output on purpose. In that case, write the new contract test before the edit.

Close the pass

Merge only after the golden row passes unchanged. The diff should show one extracted predicate and its tests. Anything larger waits for a second characterization pass.

If you already hold a free server seat, rerun that golden row there. Keep the model out of the expected-value file. The fixture you captured is the contract for this split.

Lock mkdir Failures Before One Path Extract

Dakota Huang — Fri, 09 Oct 2026 05:11:54 +0000

Extract nothing until side effects have a frozen contract. A messy path helper often creates directories while building strings. Split that helper too early and a swallowed OSError disappears.

This walkthrough pins current behavior before any edit. Then it applies one small reversible change only. The samples are labeled proposals, not executed runs.

Why this extract fails in review

Legacy report code often mixes three jobs in one function. It joins path parts into one returned string. It creates a parent directory as a side effect.

It also hides permission errors from every caller. A rename looks harmless in a small diff. A later import can change when that directory appears.

Characterization tests catch that drift before the extract. They record what the code does on today's inputs. They do not record what a cleaner design would do.

The messy helper

The function below is an unexecuted teaching sample. Confirm it against your tree before you trust it. Do not paste it over a live module.

# proposal: unexecuted sample, confirm on your tree
import os
from pathlib import Path

def build_report_path(root, name, stamp, make=True):
    raw = os.path.join(str(root or ''), str(name or 'report'))
    if stamp:
        raw = raw + '-' + str(stamp)
    path = Path(raw)
    if make:
        try:
            path.parent.mkdir(parents=True, exist_ok=True)
        except OSError:
            return None
    return str(path)

This function returns either a string or None. None means mkdir failed, not a missing name. Callers may branch on that exact None result.

Blank root becomes an empty string before the join. A missing name becomes the literal word report. A missing stamp skips the suffix entirely here.

Integer zero is also a missing stamp here. In Python, zero is falsy, so the branch skips. The text zero is truthy and still appends.

That distinction is a contract, not a style nit. A cleanup that treats zero as present will move files. Pin that distinction before you extract the join.

What to freeze

Do not freeze comments, quotes, or line length. Freeze observable results that callers can already see. Four caller-visible outcomes matter for this path helper.

A normal call returns one stable path string.
Empty root and blank name still follow today's join rules.
A failed mkdir returns None and does not raise.
A false make flag skips creation and still returns a path.

A later extract may keep the same strings. It can still move the mkdir call earlier. That move is a behavior change even when strings match.

An existing parent must remain a successful mkdir. The exist_ok flag already treats that directory as fine. Do not convert that success into a new error.

Decision table

Use this table before you edit a line. Each row names one observation from the current helper. The last column limits what the first change may do.

Observation	Current result	First change allowed
root set, name q, stamp 01	string ending in q-01	keep that exact string
root empty, name empty, stamp missing	string ending in report	keep today's join rules
parent path is a file, make true	None, no exception	keep swallowed OSError
make false	string, no new directory	do not add a mkdir
stamp integer 0	no suffix, because 0 is falsy	do not treat 0 as present
stamp text 0	suffix -0	do not drop a truthy stamp
parent directory already exists	string, no exception	keep exist_ok success

Build assertions with os.path.join rather than hardcoded slashes. Join rules differ across common operating systems today. A slash literal will fail on one of them.

Numbered workflow

1. Capture the call surface

List every caller argument shape before you edit. Include None, empty string, integer zero, and a text stamp. Write those shapes into the test file first.

2. Write characterization tests

Assert the current return value and the current side effect. Use a temporary directory created by the test. Point a failed parent at a file so mkdir raises.

3. Run the suite on untouched code

The first run should pass against today's helper. A failing new test means you guessed the behavior. Update the assertion to match the code, not the reverse.

4. Extract only the pure join

Move string assembly into one new pure function. Leave mkdir and the OSError handler in place. Keep the public name and the argument order unchanged.

5. Re-run the same tests

Every characterization test must still pass without edits. If one test fails, revert the extract immediately. Do not edit expectations to hide a moved side effect.

6. Stop after one extract

One pure join extract is the entire change. A type-hint sweep belongs in a later commit. A logging add also belongs in a later commit.

Tests that lock the contract

These tests are a proposal you should run locally. They use only modules from the standard library. They were not executed while preparing this article.

# proposal: unexecuted; run before you trust the assertions
import os
import tempfile
import unittest
from pathlib import Path

import report_paths

class TestBuildReportPath(unittest.TestCase):
    def test_text_stamp_is_appended(self):
        root = tempfile.mkdtemp(prefix='path-pin-')
        got = report_paths.build_report_path(root, 'q', '01', make=False)
        self.assertEqual(got, os.path.join(root, 'q-01'))

    def test_zero_stamp_is_skipped(self):
        root = tempfile.mkdtemp(prefix='path-pin-')
        got = report_paths.build_report_path(root, 'q', 0, make=False)
        self.assertEqual(got, os.path.join(root, 'q'))

    def test_blank_name_uses_report(self):
        root = tempfile.mkdtemp(prefix='path-pin-')
        got = report_paths.build_report_path(root, '', None, make=False)
        self.assertEqual(got, os.path.join(root, 'report'))

    def test_failed_mkdir_returns_none(self):
        root = tempfile.mkdtemp(prefix='path-pin-')
        blocker = Path(root) / 'not-a-dir'
        blocker.write_bytes(b'x')
        parent = blocker / 'child'
        got = report_paths.build_report_path(str(parent), 'q', '01', True)
        self.assertIsNone(got)

    def test_make_false_creates_nothing(self):
        root = tempfile.mkdtemp(prefix='path-pin-')
        before = set(os.listdir(root))
        report_paths.build_report_path(root, 'q', '01', make=False)
        self.assertEqual(set(os.listdir(root)), before)

    def test_existing_parent_still_returns_string(self):
        root = tempfile.mkdtemp(prefix='path-pin-')
        got = report_paths.build_report_path(root, 'q', '01', make=True)
        self.assertEqual(got, os.path.join(root, 'q-01'))

The failure case writes a file, then uses that file as a parent. mkdir with parents enabled must raise OSError there. The helper catches OSError and then returns None.

NotADirectoryError is a subclass of OSError in current Python. The broad handler already catches that OSError subclass. Do not narrow the except clause in this commit.

A false make flag must not create the joined path. The directory listing before and after should match. If the listing grows, the flag no longer means skip.

The existing-parent test expects a string, not None. That row guards exist_ok from a careless edit. Delete the temp directory in your real suite after each case.

The smallest safe change

# proposal: smallest extract; tests above must still pass
def join_report_path(root, name, stamp):
    raw = os.path.join(str(root or ''), str(name or 'report'))
    if stamp:
        raw = raw + '-' + str(stamp)
    return raw

def build_report_path(root, name, stamp, make=True):
    path = Path(join_report_path(root, name, stamp))
    if make:
        try:
            path.parent.mkdir(parents=True, exist_ok=True)
        except OSError:
            return None
    return str(path)

The public function keeps its name and signature. The new function performs no mkdir and no catch. Callers of the public function still see None on failure.

A future commit can switch selected callers to the pure function. That switch is a separate behavior decision later. It does not belong beside this first extract.

Do not resolve during the extract

The public function returns a Path string, not the raw join. Wrapping with Path can collapse repeated separators. Returning the raw join from the public function would drift.

Path construction does not resolve parent-directory segments. Path.resolve can turn a relative string into an absolute path. It can also expand a symlink to another target.

Callers that compare strings will see a new value. Leave resolve for a later separate contract change. Keep the wrap inside the original function for now.

Commands to run before review

Run the characterization module before you open the diff. Then run that same module again after the extract. Both runs should report the same passing count.

python -m unittest report_paths_contract -v

If you prefer a one-file check, pass the test path directly. Keep the command in the commit message or the review note. A reviewer should be able to repeat it without extra setup.

python -m unittest discover -s tests -p 'test_report_paths*.py' -v

Do not add network calls to this suite. Do not read a developer config file inside these tests. The contract should depend only on arguments and a temp directory.

Where a free coding pass fits

You can draft the table and the tests with a coding assistant. MonkeyCode offers free model access and a free server option. Disclosure: This article was prepared as part of MonkeyCode's product outreach.

Use free model access to propose assertions from the helper you paste. Use the free server only as an isolated place to run that suite. Do not treat either option as a measured benchmark.

This article states no quota, model name, hardware shape, or retention period. Confirm those limits in current product docs before you rely on them. Availability alone is not a performance or capacity claim.

Keep the assistant outside the decision to change behavior. If a suggestion fixes the falsy zero stamp, reject it. The characterization file is the authority, and the model is only a drafter.

One practical check still belongs in this workflow. Paste the helper and ask for tests that lock current returns. Run those tests yourself on the untouched code.

A suggestion that fails on untouched code is a guess. Discard it or rewrite the assertion to match reality. Never change the helper so a guessed test can pass.

Limits of this approach

This workflow does not prove any thread safety property. Two callers can still race inside the same mkdir. It also does not prove path traversal safety.

A name with a parent-segment escape can still leave root. That risk needs a separate allow-list or a resolved-path check. Do not hide that check inside this extract.

The method fails when observed behavior is non-deterministic. Time-based stamps and random suffixes will flake under assertion. Freeze those inputs before you compare returned strings.

Network mounts and full disks can also change OSError timing. If you cannot force the failure, do not assert a specific errno. Assert only the None return you can reproduce.

Skip this method when a full contract suite already covers the helper. Also skip it during an active data-loss incident. Stop the bad write first, then characterize after containment.

Skip it when the first change must alter behavior on purpose. A deliberate new suffix rule is not a characterization task. Write the new contract, then change code to match that new contract.

Review checklist

Tests pass on the helper before the diff.
The diff moves join logic and nothing else.
A caught OSError still returns None to callers.
A false make flag still creates nothing new.
Public names and argument order stay exactly put.
An integer zero stamp still skips the suffix.
No second refactor rides along in the same commit.

After the pin

Run the characterization file once more on a clean checkout. Open one commit that contains the tests plus the extract. The message should name the frozen outcomes, not a vague cleanup.

A later reader should see why None still exists. The swallowed error is recorded behavior, not an accident you forgot. Removing it requires a new contract and a new commit.

A second reader can still help after the local run. Ask a free model to hunt moved side effects. Your local test run remains the only merge gate.

Pin Report Bytes Before You Extract One Parser

Dakota Huang — Fri, 09 Oct 2026 01:47:53 +0000

Freeze current report bytes before you extract a parser. The smallest safe change keeps every known bug. A later commit can fix that known bug.

A messy function often writes files and parses flags together. Splitting it first can hide a behavior change. Characterization tests record the old contract before any split.

Why this order matters

Legacy helpers mix parsing, clocks, and disk writes. One rename can change error text by accident. Tests that only check happy paths miss that drift.

Michael Feathers named these behavior locks characterization tests. They lock observed behavior, including known product defects. They do not define the ideal future design.

The term comes from Working Effectively with Legacy Code. That book treats pins as discovery, not as specs. Use the pins to detect drift, not to praise the mess.

The sample mess

The sample below is a proposal, not a production module. It was not executed while drafting this article. Treat the outputs as the contract you must pin.

# Proposal only: this module was not executed in this draft.
import json
from pathlib import Path

def run_job(argv, out_dir):
    if not argv or argv[0] != "emit":
        return 2, "usage: emit <name>\n"
    name = argv[1] if len(argv) > 1 else ""
    if name.strip() == "":
        return 3, "name missing\n"
    path = Path(out_dir) / f"{name}.json"
    payload = {"name": name, "ok": True}
    text = json.dumps(payload, separators=(",", ":"))
    path.write_text(text, encoding="utf-8")
    return 0, f"wrote {path.name}\n"

Three observable facts matter before any code split. Exit codes must stay two, three, and zero. The stderr-style text must keep its trailing newline.

File bytes stay compact JSON with no extra space. Spaces inside the name stay inside the file name. Those quirks are recorded data, not cleanup tasks.

Step 1 — Record seams before you touch code

List every input that the function reads today. List every output that a caller can observe. Do not list the design you wish you had.

Seam	Current observation	Safe to change now
argv missing or not emit	code 2 and usage text	no
blank or missing name	code 3 and name missing	no
name with inner spaces	file name keeps spaces	no
JSON body	compact separators, ok true	no
clock, random, network	unused in this function	n/a

This seam table is the entire change budget. Anything unmarked in that table stays fully frozen. A parser extract may not edit those rows.

Step 2 — Add characterization tests

Use pytest and tmp_path for the file seam. Assert return codes, text, and exact file bytes. Do not normalize whitespace in the golden text.

Install pytest in the same interpreter you will pin. The tmp_path fixture is documented in the pytest how-to pages. Link those docs beside the new test file.

https://docs.pytest.org/en/stable/

# Proposal only: these tests were not executed in this draft.
from report_job import run_job

def test_usage_when_command_missing(tmp_path):
    code, text = run_job([], tmp_path)
    assert code == 2
    assert text == "usage: emit <name>\n"

def test_missing_name_keeps_code_three(tmp_path):
    code, text = run_job(["emit", "   "], tmp_path)
    assert code == 3
    assert text == "name missing\n"
    assert list(tmp_path.iterdir()) == []

def test_spaces_survive_in_file_name(tmp_path):
    code, text = run_job(["emit", "Ada Lovelace"], tmp_path)
    assert code == 0
    path = tmp_path / "Ada Lovelace.json"
    assert path.read_bytes() == b'{"name":"Ada Lovelace","ok":true}'
    assert text == "wrote Ada Lovelace.json\n"

Run the full suite before the parser extract. A red test means the pin is wrong. Fix the failing pin, not the production code.

python -m pytest test_report_job.py -q

You should commit only the green characterization pins. That green commit becomes the safe refactor baseline. The next commit may move production code only.

Step 3 — Make the smallest safe change

Extract one pure parser and leave writes behind. Keep run_job as the only disk writer here. Call the new parser from that old function.

# Proposal only: keep writes inside the old function.
def parse_emit(argv):
    if not argv or argv[0] != "emit":
        return ("usage", None)
    name = argv[1] if len(argv) > 1 else ""
    if name.strip() == "":
        return ("missing", None)
    return ("ok", name)

def run_job(argv, out_dir):
    kind, name = parse_emit(argv)
    if kind == "usage":
        return 2, "usage: emit <name>\n"
    if kind == "missing":
        return 3, "name missing\n"
    path = Path(out_dir) / f"{name}.json"
    payload = {"name": name, "ok": True}
    text = json.dumps(payload, separators=(",", ":"))
    path.write_text(text, encoding="utf-8")
    return 0, f"wrote {path.name}\n"

Re-run the same three characterization tests without edits. Those tests must stay green without assertion edits. A needed assertion change means the extract was not safe.

python -m pytest test_report_job.py -q
git diff --stat

Review the diff for one function move only. Do not edit user-facing messages in this diff. Do not rename JSON keys in this same diff.

Do not add new flags in this same commit. Do not reorder imports unless a test requires it. Stop when the diff is only the parser move.

Use this gate before you accept the extract. Every row must pass in the same commit. A single miss means you revert the move.

Check	Pass rule	Fail action
Three pins green	no assertion edits	revert the extract
Diff shape	one new function only	split the commit
Messages and bytes	identical to the pins	restore old text
Generated patch	tests only, else drop it	discard the patch

Step 4 — Use a free model only as a draft aid

Disclosure: This article was prepared as part of MonkeyCode's product outreach. MonkeyCode offers free model access and a free server option. Those two facts are the only product claims used here.

Quotas, model names, and hardware are not assumed. Duration and package images are also not assumed. Check current terms before you rely on either option.

A free model may draft the three tests from the table. Use the free server option only if it can run your suite. You still compare its output with the seam table.

Give the model the current function and the seam table. Ask for tests that fail on any text change. Reject any patch that cleans the usage string text.

Draft characterization tests only from the seam table.
Do not change production code in this patch.
Assert exact codes, text, and file bytes.
Do not fix the space-in-name quirk at all.

Run that generated draft where your runner actually exists. Keep the command log next to the tests. If the server environment differs, record the Python version in notes.

python -V
python -m pytest test_report_job.py -q --tb=short

The draft model does not approve the merge. A human checks the diff against the table. Green tests plus a small diff are the gate.

Step 5 — Stop at the first safe boundary

Do not fix the space-in-name quirk in this pass. That space-in-name quirk stays pinned on purpose here. A behavior fix needs a new test and a new commit.

Do not extract the JSON writer in the same change. Two extracts hide which move broke a byte. One function move is enough for this pass.

Keep suggested commit subjects deliberately narrow and specific. Put the pin commit before the extract commit. Do not squash them until review is done.

test: pin emit codes, text, and report bytes
refactor: extract parse_emit without behavior change

What a bad extract looks like

A bad extract changes text while moving the parser. The usage line might lose its trailing newline. The missing-name code might become a raised exception.

Those edits can look cleaner during code review. The characterization suite should turn red immediately after. Revert the production edit and keep the pins.

Compare the red assertion to the seam table. The table row is the source of truth here. Do not update the pin to match the cleaner text.

Limits of this workflow

Characterization tests lock accidents as well as intent. A later reader may treat a bug as a feature. Name the quirk in the test docstring or a nearby comment.

Exact byte asserts break on harmless JSON key order changes. This sample uses one dict and explicit separators. This sample assumes insertion-ordered dicts from Python 3.7.

If key order is not a contract, compare a parsed object instead. Keep byte asserts only for text you truly freeze. Say that comparison choice in the test name.

The tmp_path fixture does not catch cross-process file locks. It also does not catch timezone-based file writes. Add those seams only if the function uses them.

A free server may not match production packages. Pin the test interpreter in the notes you keep. Do not treat a green remote run as a release sign-off.

Free model drafts can invent incorrect exact assertions. They can also strip important trailing newline bytes. Diff every generated line against the seam table.

Who should skip this approach

Skip it when the ticket requires a behavior change now. A pin would only slow the required fix. Write the new contract test first in that case.

Skip it when the repo has no isolated runner. Shared staging data can leak into golden pins. Build a local fixture path before you record goldens.

Skip it when outputs include secrets or personal data. Golden files would copy those values into git. Redact or synthesize inputs before you assert bytes.

Skip it when timing, network, or hardware is the contract. A free server is the wrong oracle for those seams. Measure those seams on the real target instead.

What to do next

Pick one messy function with three observable outputs. Pin those outputs, then extract one pure helper. Leave the bug fix for the following commit.

If you use a hosted assistant, read the current free-model and free-server terms first. Use them to draft and run pins, not to skip review.

Hold the Wide Diff Until One Score Extract Passes

Dakota Huang — Thu, 08 Oct 2026 22:32:52 +0000

A wide model diff is not a finished refactor. Lock observable behavior before you accept any split. Then ship only the smallest change that still matches.

Messy modules hide three jobs in one file. They read input, compute a score, and write logs. One careless edit can break all three jobs together.

This walkthrough uses a tiny Python scoring module. Every listing below is an unexecuted example for local use. Adapt names and paths before you run a command.

What must stay fixed

Readers care about outputs, not internal file shape. A characterization test records those outputs before the edit. The same test must pass after the smallest extract.

Record the return value, the log text, and any other bytes. Also record the exception type on the bad path. Skip fields you cannot reproduce on a second run.

Do not assert private helper names in this pass. Do not assert source line counts inside the module. Those checks punish a safe extract that preserves behavior.

Why a wide diff fails review

A coding model often proposes three moves together. It extracts helpers, renames files, and reorders imports. You cannot tell which move changed the score.

Treat review as a gate with a written rule. Reject the patch when it touches more than one concern. Ask for a new patch that moves one function only.

A concern here means load, score, log, or imports. Count them in the diff before you discuss style. Style nits can wait until the golden test is green.

Workflow you can repeat

Follow these steps in order on a clean branch. Stop when a step fails and do not skip ahead. Each step has one job and one pass condition.

1. Freeze the fixture set

Pick three inputs that already exist in the repo. Use one happy path, one edge path, and one bad path. Store them under fixtures with names that will not drift.

Do not invent production totals for this exercise. Do not copy customer files into the sample tree. Synthetic rows are enough to lock the current contract.

2. Write the characterization test

Call the public function and capture every side effect. Compare the capture with a golden file you just recorded. Fail the test when any captured field drifts.

Keep the golden file in version control with the test. Reviewers should see the expected bytes beside the patch. A missing golden file means the gate is not ready.

3. Run the test on unchanged code

Confirm the golden file matches the current module. Treat a red test here as a fixture bug, not a product bug. Fix the fixture before you touch production code.

Run the test twice and require the same result. A flaky capture is not a valid characterization ledger. Remove clocks and random calls from this fixture first.

4. Reject the wide model diff

Read the diff and count the concerns it changes. If the diff changes two concerns, discard that patch. Request one extract of the pure score function only.

Do not negotiate a partial apply of a wide diff. Partial applies hide the hunk that actually broke output. The model can draft again against a tighter prompt.

5. Apply the smallest safe change

Move the pure score function into a new module. Leave file reads and log writes in the old module. Keep the public function name and the argument order.

Update only the import that the old module needs. Do not reformat unrelated functions in the same commit. Formatting noise makes the next review slower and weaker.

6. Re-run the same characterization test

Do not edit the golden file after the extract. A green result means observable behavior stayed fixed. A red result means you revert the extract immediately.

Inspect the assertion diff before you edit production code again. If the log text changed, the extract was not pure. Put the function back and repeat the prompt with a harder limit.

7. Consider a second extract only after green

Repeat the gate for logging or file reads later. Never stack a second extract on a red ledger. Each pass should change one concern and nothing else.

Wait for a human review between those passes. A model can suggest the next extract, not approve it. Approval stays with the person who owns the module.

Example module before the split

This listing is a proposal, not a measured benchmark. It shows the tangle you should not rewrite in one pass. No runtime numbers are claimed for this sample.

# Unexecuted example. Adapt paths before any local run.
import json
from pathlib import Path

def load_rows(path):
    raw = Path(path).read_text(encoding="utf-8")
    return json.loads(raw)

def score_rows(rows):
    total = 0
    for row in rows:
        total += int(row["points"]) * int(row["weight"])
    return total

def write_log(path, message):
    Path(path).write_text(message + "\n", encoding="utf-8")

def run_job(src, log_path):
    rows = load_rows(src)
    total = score_rows(rows)
    write_log(log_path, f"total={total}")
    return total

The public job mixes load, score, and log writes. The pure function is score_rows and nothing else. That function is the only safe first extract.

Integer casts can raise ValueError on bad rows. Capture that exception type in a separate bad-path test. Do not swallow the error while you move the function.

Characterization test you can copy

This test is also an unexecuted local example. It uses the standard library and makes no network calls. Run it with pytest after you place both files.

# Unexecuted example. Requires pytest in your local environment.
import json
from pathlib import Path
import score_job

def test_happy_path_matches_golden(tmp_path):
    src = tmp_path / "rows.json"
    log_path = tmp_path / "job.log"
    src.write_text(
        json.dumps([{"points": 2, "weight": 3}]),
        encoding="utf-8",
    )
    result = score_job.run_job(src, log_path)
    golden = {"result": 6, "log": "total=6\n"}
    actual = {
        "result": result,
        "log": log_path.read_text(encoding="utf-8"),
    }
    assert actual == golden

def test_empty_rows_score_zero(tmp_path):
    src = tmp_path / "empty.json"
    log_path = tmp_path / "job.log"
    src.write_text("[]", encoding="utf-8")
    result = score_job.run_job(src, log_path)
    assert result == 0
    assert log_path.read_text(encoding="utf-8") == "total=0\n"

def test_bad_row_raises_value_error(tmp_path):
    src = tmp_path / "bad.json"
    log_path = tmp_path / "job.log"
    src.write_text(
        json.dumps([{"points": "x", "weight": 1}]),
        encoding="utf-8",
    )
    try:
        score_job.run_job(src, log_path)
    except ValueError:
        return
    raise AssertionError("expected ValueError")

The happy-path total is 2 times 3, which is 6. The empty input total is 0 by the same loop. Those two numbers are arithmetic checks, not benchmarks.

The happy-path assertion checks the result and the log text. It does not check helper names or file layout. A later extract can move score_rows and still pass.

The bad-path test locks the exception type only. It does not lock the exception message text. Message text often changes during a harmless rename.

Decision table for the incoming patch

Use this table before you apply any model patch. Count concerns in the diff, then pick one row. The table is a review rule, not a product score.

Diff shape	Concerns touched	Decision
Extract score_rows only	1	Apply, then re-run the golden tests
Extract plus a rename	2	Reject and request a smaller patch
Extract plus import reorder	2	Reject until imports are a later pass
New dependency added	2 or more	Reject for this characterization pass
Golden file edited by the model	n/a	Reject and restore the recorded golden
Behavior change requested in the prompt	n/a	Stop and write a new spec instead

A one-concern row is the only apply decision. Every other row waits for a narrower diff. Restore the branch if a rejected hunk was already applied.

Where a narrow model draft fits

Disclosure: This article was prepared as part of MonkeyCode's product outreach. MonkeyCode, as supplied for this draft, offers free model access. That supplied note also includes a free server option.

Ask the model only to draft the one-function extract. Use the free server only when your current terms allow it. You still own the accept or reject decision.

Treat the prompt below as a proposal, not a guarantee. It limits the model to one concern and one new file. Edit the names so they match your module.

Extract only score_rows into score_math.py.
Do not rename run_job.
Do not reorder imports in other files.
Do not edit tests or golden files.
Return a diff that changes one concern.

Paste the model diff into your review branch, not into main. Run the characterization tests before you create any commit. Discard the diff when the table says reject.

If you already have MonkeyCode access, try this gate on one messy module. Keep the patch only when both golden tests stay green. Leave the wide rewrite for a later, separate pass.

Commands that keep the loop small

These commands assume a local checkout and a pytest install. They are examples, not proof of a remote execution. Replace the test path if your layout differs.

python -m pytest tests/test_score_job.py -q
git diff --stat
git diff --name-only

Read the name list before you read the hunks. One new module plus one caller edit is the target shape. More files mean you stop and request a smaller patch.

A quiet pytest run is the pass signal for this gate. A failed assertion is a stop signal, not a prompt to improvise. Revert first, then ask the model for a narrower diff.

Limitations you should state in review

Characterization tests miss behavior that you never recorded. A green run does not prove thread safety or speed. It only proves the captured fields stayed the same.

This sample ignores permissions, clocks, and network calls. Add those captures before you extract code that uses them. Do not treat this fixture as a full production suite.

Free model access can still propose a wide diff. A free server can still execute the wrong test file. Neither option replaces the concern count in the table.

This draft states no speed, cost, or uptime figures. Those facts were not supplied and must not be guessed. Check current product terms yourself before you depend on access.

The integer score rule is a teaching stand-in, not your domain rule. If your formula uses floats, lock rounding in the golden file. Otherwise a harmless refactor can look like a behavior change.

Who should skip this approach

Skip this gate when the module has no stable outputs. Skip it when the next change must alter behavior on purpose. Write a new spec first if the score rule itself must change.

Skip it for security fixes that need a behavior change. A characterization test would freeze the bug you must remove. Use a failing regression test for that case instead.

Skip it when you cannot run tests on the target branch. A free server does not help if secrets block the job. Do not paste private fixtures into any hosted prompt.

Skip it when the team has no reviewer for the final diff. A green test is necessary, but it is not the whole review. Ownership of the merge stays with a person, not a model.

Closing rule

Start from the conclusion and keep every pass small. Lock outputs, reject wide diffs, and extract one function. Commit only after the same golden tests stay green.