DEV Community: Dakota Wu

Require an Empty Fixture Diff Before Extracting a Batch Loop

Dakota Wu — Sun, 11 Oct 2026 21:09:09 +0000

A late cleanup request arrived with a four-hundred-line diff that rewrote validation, deduplication, and persistence in one pass. The existing tests covered only the happy path, so a green CI run could not explain the legacy rows. The reviewer needed a smaller change that preserved every observed output before any structural boundary was allowed to move. This composite scenario shows how to freeze those outputs, then accept only the smallest safe edit.

The module under review is a batch upload normalizer that grew by successive tickets rather than by design. It reads a list of records, fills missing defaults, drops exact repeats, and writes survivors to storage. Those four jobs share one function, so a cleanup that touches all of them cannot be reviewed as one claim. The method below separates observation from edit, and it does not depend on any particular assistant.

Name the behavior you will freeze

Before changing code, write down the inputs that already matter and the outputs you are willing to treat as current truth. Include awkward rows from production samples, not only the tidy examples attached to the latest ticket. A characterization file is a pinned record of those pairs, not a statement that the behavior is desirable. If a row is known to be wrong, mark it as accepted debt instead of silently correcting it during the same change.

Three observations keep the freeze honest when the repository is already messy.

Record the returned list and the store payload, because a matching return can still hide a second write.
Preserve the original row order, because a sort that looks cleaner can change which duplicate survives.
Keep skipped rows visible in the fixture notes, because a deleted branch is still a behavior change.

That list is the review contract for this module, and it should stay visible in the pull request description. It is narrower than a repository-wide characterization suite, and it is not a license to rewrite neighboring helpers. This pass does not hash a repository-wide side-effect ledger, and it does not ask you to freeze every neighboring seam. The next section turns the contract into a local command you can rerun after every proposed diff.

Pin a fixture before the extraction

The following Python example is a proposed harness, not a log from a measured production run. It uses a memory store so the test process does not touch a real database or a shared queue. The cases cover a blank SKU, a negative quantity, an exact repeat, and a lowercase SKU that the current code uppercases. Run the capture against the untouched function, then commit the fixture before you accept any cleanup.

import json
from pathlib import Path

class MemoryStore:
    def __init__(self):
        self.batches = []

    def write(self, rows):
        self.batches.append([dict(row) for row in rows])

def normalize_upload_batch(records, store):
    seen = set()
    kept = []
    for record in records:
        sku = (record.get('sku') or '').strip().upper()
        qty = record.get('qty', 0) or 0
        if not sku or qty < 0:
            continue
        key = (sku, int(qty))
        if key in seen:
            continue
        seen.add(key)
        kept.append({'sku': sku, 'qty': int(qty)})
    store.write(kept)
    return kept

CASES = [
    {
        'name': 'blank-sku',
        'records': [{'sku': '  ', 'qty': 2}],
        'debt': False,
    },
    {
        'name': 'negative-qty',
        'records': [{'sku': 'ab1', 'qty': -1}],
        'debt': False,
    },
    {
        'name': 'case-and-repeat',
        'records': [
            {'sku': 'ab1', 'qty': 2},
            {'sku': ' AB1 ', 'qty': 2},
            {'sku': 'ab1', 'qty': 3},
        ],
        'debt': False,
    },
]

def capture(cases):
    report = []
    for case in cases:
        store = MemoryStore()
        returned = normalize_upload_batch(case['records'], store)
        report.append({
            'name': case['name'],
            'debt': case['debt'],
            'returned': returned,
            'written': store.batches,
        })
    return report

def main():
    path = Path('batch_characterization.json')
    payload = json.dumps(capture(CASES), indent=2) + '\n'
    path.write_text(payload, encoding='utf-8')
    print('wrote', path)

if __name__ == '__main__':
    main()

Compare the fixture, do not skim the diff

A second, ordinary command compares a fresh capture with the fixture you already committed to the branch. The comparison is a textual check of the JSON, not a visual skim of a large assistant diff. If you later correct a debt row, change the fixture in a separate commit and state the product reason in that commit message. Until you trust the harness, treat a non-empty fixture diff as a failed review rather than as a suggestion.

Save the harness as capture_batch.py beside the fixture so the commands below match the file you run.

python capture_batch.py
git diff -- batch_characterization.json

The sample function above is embedded so a reader can follow the article without cloning a repository. In a real repository, import the existing function instead of pasting a simplified copy into the test file. A pasted copy can drift from the production function and then bless the wrong behavior during review. Keep the fixture next to the module so a reviewer can open both without searching the whole tree.

Score the smallest safe change

After the fixture is committed, the only edit this pass allows is an extraction of the pure selection loop. The wrapper may call the new function and then perform exactly one write to the existing store. It may not add a sort, a new skip rule, a retry, or a second store call. The table below is the acceptance gate for the diff, and a single failed row is enough to reject the change.

Check	Accept this pass	Send it back
Files touched	The one module that owns the batch function	Any helper outside that file
Fixture JSON	Unchanged after a local rerun	Any added, dropped, or reordered field
Store writes	One write, matching the returned rows	An extra write, a cleared batch, or a write before selection
New branches	None	A fallback, a retry, or a temporary compatibility flag
Debt rows	Still marked debt in the fixture	Quietly corrected inside the cleanup

The extraction that the gate allows

The extracted shape that satisfies every row of the table looks like the unexecuted sketch below. It remains a proposal until you rerun the capture and the fixture diff is completely empty. Notice that the skip rules are copied, not improved, because an improvement is a behavior change and belongs in a later commit. The wrapper stays responsible for the write, so persistence bugs are not mixed into the pure move.

def select_upload_rows(records):
    seen = set()
    kept = []
    for record in records:
        sku = (record.get('sku') or '').strip().upper()
        qty = record.get('qty', 0) or 0
        if not sku or qty < 0:
            continue
        key = (sku, int(qty))
        if key in seen:
            continue
        seen.add(key)
        kept.append({'sku': sku, 'qty': int(qty)})
    return kept

def normalize_upload_batch(records, store):
    kept = select_upload_rows(records)
    store.write(kept)
    return kept

Follow the same four steps

Commit the characterization fixture that you generated from the untouched function before any extraction work begins.
Extract only the selection loop into a pure helper, and leave the storage write inside the original wrapper.
Rerun the local capture after that extraction and require an empty diff on the committed fixture file.
Schedule debt corrections, retries, and storage changes as later commits that carry their own expected results.

That order matters more than the size or brand of the assistant that happened to propose the cleanup. A small extraction can still be wrong if you regenerate the fixture after the edit and then treat the new file as the baseline. Commit the baseline first, or the acceptance gate has nothing stable left to protect later. If step three fails, restore the extraction and inspect the case, rather than widening the diff to force a match.

Let an assistant draft, then keep the gate local

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

A coding assistant can draft fixture cases or the extraction sketch after you have already named the rows you care about. For this draft, the operator supplied two availability claims: free model access and a free server option. This article does not state model names, token quotas, hardware size, duration, or benchmark scores, because those details were not provided as primary sources. Check the project documentation on the day you start, because availability terms can change and should not be copied from an older post.

The useful split should stay small even when the assistant is allowed to see the whole repository. Ask it to propose cases that match the contract, then paste those cases into the harness and run the capture yourself. Ask for the extraction only after the fixture is committed, and reject any diff that fails a row in the table. A free server can be a convenient place to run that capture when your laptop cannot match the language version. The committed fixture still belongs in the repository you review, not only on the temporary machine.

If that gate matches how you already review cleanups, read the current access notes before you try it. Then run the same fixture workflow on one module you can execute on a machine you control. Keep the product optional: the harness, the table, and the empty fixture diff are the parts a teammate can reuse without an account. A reviewer should never treat a model-written explanation as proof that the fixture file remained stable.

Limitations and who should skip this

This approach freezes current behavior, including bugs that nobody has yet scheduled for a product fix. It is a poor fit when the ticket requires a visible behavior change inside the same pull request. It is also a poor fit when you cannot obtain representative rows, because an empty fixture will bless whatever the first draft happens to emit. A memory store does not prove transaction order, locking, or partial failure, so do not use it to clear a data-migration change.

Skip the gate as your only review when the diff touches authentication, billing totals, or deletion. Those areas need explicit expected outcomes, not a snapshot of whatever the old code already did. Do not plan a team rollout around an unverified free quota or an assumed server lifetime from an old post. If today's documentation does not confirm the access terms you need, treat the assistant as optional. Keep the harness on a machine you control rather than on a shared environment you have not reviewed.

The closing claim stays modest, and a reviewer can audit it from the fixture diff alone. A four-hundred-line cleanup becomes reviewable when one characterized seam moves and the fixture file stays still. Everything else can wait for a later commit that states the behavior it intends to change. That later commit should carry its own cases, rather than borrowing the freeze you used to keep this extraction honest.

Freeze a Golden Trace Matrix Before the One-Seam Cleanup

Dakota Wu — Sat, 10 Oct 2026 17:39:14 +0000

This opening is an illustrative composite, not a report of a named production incident or a measured outage. A billing helper in a five-year-old repository still writes an audit line while it computes a customer discount. Three optional flags arrived through separate pull requests, and none of those flags share one documented contract. An unbudgeted agent rewrite then dropped that audit line for empty customer codes, even though the returned discount stayed numeric.

Why the large cleanup failed

The cleaner diff was accepted because review focused on names and nesting instead of the branch production actually hit. That pattern is common in messy modules, where important behavior lives in side effects rather than in the returned number. A characterization pass has to record both, or the next cleanup will look tidy while a nightly job changes. Any later agent draft stays downstream of that recorded contract, and it does not choose the row.

A messy module usually breaks during a refactor at one narrow seam, not across every line of the file. The risky place is often an uncovered branch, a silent write, or a default that treats missing input as zero. A broad rewrite hides that drift among renames, so reviewers spend their time on style rather than behavior. The safer sequence is to pin current results first, then permit only the smallest edit those pins already cover.

That sequence costs more attention on the first afternoon, and it usually costs less time on the first regression. You record what the function does today, including results that a later ticket may classify as bugs. You then allow one named seam to move, and you reject any diff that changes a row outside that budget. An agent may draft the edit, but the budget should come from cases you already stored and reviewed.

What the seam budget counts

A seam, in this workflow, is one decision the function already makes for a recognizable class of inputs. Examples include a missing customer code, an empty customer code, a gold tier, or a write onto the audit log. The budget is a small table you can recompute from the same cases whenever a new diff appears. A seam with no pinned case is not eligible for an agent edit during the current pass.

The score stays crude on purpose, because a crude score is easier to audit than a narrative summary of the file. Count pinned cases, count distinct returned values, and count side-effect events that those cases actually recorded. Do not treat the score as profiler coverage, and do not treat it as permission to redesign the surrounding module. It only answers which single seam is eligible to change next, given evidence you already checked in.

Apply these eligibility rules before you open a remote drafting session:

Every eligible seam needs at least two pinned cases with meaningfully different inputs.
A side effect belongs to the contract when any pinned case records that event.
Seams with zero pinned cases stay frozen, even when the implementation looks obviously wrong.
The budget names one seam in the diff message, and every other seam remains out of scope.

A local harness you can adapt

The Python below is a local gate proposal, not a claim that this exact file ran in a production repository. It executes a function against a fixed matrix, stores outputs beside side effects, and rejects an unpinned target seam. You can replace the sample function with the one you own, then commit the matrix beside the existing tests. The sample treats missing and empty codes as different seams, because production defects often hide in that split.

from dataclasses import dataclass, field
from typing import Callable

@dataclass(frozen=True)
class Case:
    name: str
    customer_code: str | None
    tier: str | None

@dataclass(frozen=True)
class Trace:
    name: str
    amount: int
    events: tuple[str, ...] = field(default_factory=tuple)

def apply_discount(code, tier, audit):
    # Illustrative baseline, not a recommended pricing implementation.
    if code is None:
        return 0
    if code == "":
        audit.append(f"empty:{tier}")
        return 0
    if tier == "gold":
        audit.append(f"gold:{code}")
        return 80
    audit.append(f"default:{code}")
    return 95

def seam_for(case: Case) -> str:
    if case.customer_code is None:
        return "missing_code"
    if case.customer_code == "":
        return "empty_code"
    if case.tier == "gold":
        return "gold_tier"
    return "default_tier"

def run_matrix(fn: Callable, cases: list[Case]) -> list[Trace]:
    traces = []
    for case in cases:
        audit: list[str] = []
        amount = fn(case.customer_code, case.tier, audit)
        traces.append(Trace(case.name, amount, tuple(audit)))
    return traces

def budget(cases: list[Case], traces: list[Trace], target: str) -> dict:
    pinned = [case for case in cases if seam_for(case) == target]
    if len(pinned) < 2:
        return {"target": target, "eligible": False, "reason": "need two pins"}
    shapes = []
    for case, trace in zip(cases, traces):
        if seam_for(case) == target:
            shapes.append(str(trace.events))
    return {
        "target": target,
        "eligible": True,
        "pinned_cases": [case.name for case in pinned],
        "side_effect_shapes": sorted(set(shapes)),
        "allowed_change": "one seam only",
    }

def same_contract(golden: list[Trace], fresh: list[Trace]) -> bool:
    left = [(item.name, item.amount, item.events) for item in golden]
    right = [(item.name, item.amount, item.events) for item in fresh]
    return left == right

Commands that keep the gate local

Store the golden traces beside the module, and compare those traces again after every proposed edit lands. A short command wrapper around the two functions above is enough for the first version of this local gate. The shell lines below assume a tiny argument parser that calls the matrix runner and the comparison helper. They illustrate the intended workflow, and they are not evidence that a particular repository already ships this file.

python3 seam_budget.py --matrix cases.json --write-golden golden.json
python3 seam_budget.py --matrix cases.json --check golden.json
python3 seam_budget.py --matrix cases.json --target empty_code --budget

The first command records the current contract, including audit events, before anyone starts to rewrite the function. The second command should exit nonzero when a fresh run disagrees on amount or on the recorded events. The third command prints whether the named seam has two pins and may enter the one-seam budget. If that check fails, stop and read the drifted row before you discuss naming, formatting, or structure.

A starter matrix

The matrix below is enough to expose the missing-code, empty-code, gold, and default seams in the sample. Notice that empty input and null input are separate rows, because the sample writes an audit event for only one of them. Gold has two rows so that seam can become eligible, while a single gold row would fail the two-pin rule. Replace the values with fixtures from your module, and keep customer identifiers synthetic rather than copied from production.

[
  {"name": "missing", "customer_code": null, "tier": "gold"},
  {"name": "empty_gold", "customer_code": "", "tier": "gold"},
  {"name": "empty_std", "customer_code": "", "tier": "std"},
  {"name": "gold_ok", "customer_code": "c-1", "tier": "gold"},
  {"name": "gold_other", "customer_code": "c-2", "tier": "gold"},
  {"name": "default_ok", "customer_code": "c-3", "tier": "std"}
]

With that file, budget(..., target="empty_code") is eligible, and budget(..., target="missing_code") is not. The missing-code seam has only one row, so the rule keeps it frozen until you add a second pin. That split is the practical difference between a cleanup you can review and a rewrite that drifts an untested branch. Run the check locally before you ask any editor, human or remote, for a patch.

When a free drafting session is in scope

Only a green local check should precede a remote draft, and the draft should name the budgeted seam in the prompt. Disclosure: This article was prepared as part of MonkeyCode's product outreach. The operator supplied two availability claims for this draft: free model access, and a free server option. The operator also describes MonkeyCode as an open-source project that can host this kind of drafting session.

This article does not name models, token quotas, hardware sizes, or a duration, because those details were not verified from a primary source here. Paste the frozen matrix, the chosen seam, and a clear instruction to leave every other branch untouched. Ask for a patch that preserves every golden event, except where you already edited the golden file yourself. Re-run the local check on your own machine after the diff returns, and discard the draft if any unbudgeted row moves.

The remote session can make that bounded edit easier to try, but it does not become the acceptance gate. Keep the remote prompt limited to the function text, the matrix, and the seam name from the budget output. A free server session is a reasonable place to draft that single patch when the matrix already lives in the repository. The same local check still has to pass on your machine before anyone merges the returned diff.

Choosing the next hour of work

The table below is a workflow control for this cleanup, not a performance comparison and not a vendor benchmark. It separates work you must finish locally from work a remote draft may attempt after the gate is green. Read the row that matches the repository you have today, not the row you wish the repository had. If two rows apply at once, use the stricter row and keep the agent session closed until the gap is fixed.

Situation	Local action	Remote draft
Target seam has two or more pins	Freeze the golden file	Allowed for that seam only
Target seam has only one pin	Add a second case first	Not yet
Any pin records a side effect	Treat the event as contract	Do not delete it in this pass
Desired work spans three seams	Split the work into passes	Refuse a combined diff
Exercise needs a live payment API	Stub the call or stop	Do not point a session at production

A remote session remains optional even on the eligible row, because a local editor can make the same narrow change. The value of the session is convenience when you want a draft against the pinned matrix, not authority over the contract. Keep secrets, customer dumps, and production credentials out of the prompt regardless of which row you select. If the remote view cannot see the repository, copy only the function and the cases you already pinned.

Limitations you should state in the pull request

Characterization pins preserve current behavior, including defects you have not yet decided to fix in this pass. If the empty-code branch should stop writing an audit line, change the golden row in a separate commit first. Otherwise the gate will correctly reject the behavior change you actually intended to ship this week. That extra commit makes the intended drift reviewable without mixing it into a rename or a formatting sweep.

The scorer does not observe concurrency, time zones, or input combinations that the matrix never listed. Two pinned cases can still miss a third flag combination that production sends on a particular weekday. Add a case when a real input appears, instead of widening the agent prompt to cover unknown branches. A wider prompt is how a one-seam budget quietly becomes a whole-file rewrite with no new evidence.

Free model access and a free server option are availability claims for this draft, not a promise about next quarter. Do not copy a quota, a machine size, or a permanent allowance into the team runbook from these paragraphs. If either option is unavailable when you sit down, the local gate still stands without any remote session. The comparison and the budget do the real work, and they do not depend on a particular hosted editor.

Skip this approach when nobody on the team can review the resulting diff carefully, line by line. Skip it when the requested change is a redesign across several modules rather than one local seam. Skip it when the code cannot be exercised without live customer data or credentials you must not paste. An agent draft of an unpinned module repeats the failure already described in the composite opening above.

Checklist before you merge

Confirm the budget names one seam and lists at least two pinned cases.
Confirm the golden file changed only where you intended a behavior change.
Confirm side-effect events still match on every seam the budget did not name.
Confirm the remote draft was not accepted without a fresh local check.

That sequence lets a messy repository move without treating a shorter function as proof of behavioral safety alone. The original artifact is the seam budget together with the golden comparison, and any agent session stays downstream of both. Review the returned diff against the table, then merge only when every unbudgeted row is still identical.

Limit a Messy Adjuster Cleanup to Calls You Have Already Recorded

Dakota Wu — Fri, 09 Oct 2026 13:40:57 +0000

Consider a checkout service that accumulated one function applying coupons, tax rounding, and partial refunds in a single pass. That function returned a payable total, yet it also inserted an audit row and mutated the cart in place. An assistant then proposed a broad cleanup that split the file into six new modules and renamed several helpers. The review would stall if the team could not name which outputs were already guaranteed by an executable check.

Start from a call set, not a target layout

The useful starting point is a small call set whose outputs a current caller already depends on today. Each recorded call should carry the inputs that change money and the fields a downstream job already reads. Side effects belong in that record when a missing write would become a production incident for the on-call reader. If a path has no current caller and no incident history, leave that path outside the first change budget.

This worked example uses a fictional apply_adjustment module so the method can be copied without borrowing a private repository. The numbers below are illustrative fixtures, not production metrics collected from a named company or incident. Treat every expected value as something you must regenerate on the current code before you trust it.

What the messy function is allowed to promise

The function currently mixes three decisions that tend to fail in different ways during a structural cleanup. Coupon application can drop the subtotal to zero before any tax amount is computed on the remainder. Tax rounding can change a single cent when the order of arithmetic operations shifts inside the function. A partial refund can subtract money that the coupon had already reduced from the same payable total.

Those three paths are enough to fund a first characterization budget without inviting a wider rewrite. A fourth path, such as a loyalty multiplier, stays unrecorded until some caller proves that it matters. Expanding the budget before the first edit usually recreates the broad rewrite you were trying to avoid.

Three calls that pin the current contract

A standard cart applies a ten percent coupon, then rounds tax on the reduced subtotal, and writes one audit row.
A zero subtotal after the coupon must return a zero total and must not insert a negative tax line.
A partial refund must reduce the payable total without applying the same coupon a second time afterward.

Record outputs before anyone edits

The runner below is a proposed example, and it has not been executed against a production repository for this article. It loads a JSON call list, invokes the current function, and writes one golden file per call. A later check fails when the payable total, the audit payload, or the mutated cart fields differ from that file.

# proposal: not executed for this article
import json
from pathlib import Path

def record(calls_path: Path, golden_dir: Path, apply_adjustment) -> None:
    golden_dir.mkdir(parents=True, exist_ok=True)
    calls = json.loads(calls_path.read_text())
    for call in calls:
        result = apply_adjustment(call["cart"], call["coupon"], call["refund"])
        payload = {
            "total": result.total,
            "audit": result.audit,
            "cart": result.cart,
        }
        target = golden_dir / f"{call['id']}.json"
        target.write_text(json.dumps(payload, sort_keys=True, indent=2) + "\n")

def check(calls_path: Path, golden_dir: Path, apply_adjustment) -> list[str]:
    failures = []
    calls = json.loads(calls_path.read_text())
    for call in calls:
        result = apply_adjustment(call["cart"], call["coupon"], call["refund"])
        actual = {"total": result.total, "audit": result.audit, "cart": result.cart}
        expected = json.loads((golden_dir / f"{call['id']}.json").read_text())
        if actual != expected:
            failures.append(call["id"])
    return failures

A companion call file keeps the budget visible in review, which matters more than a clever assertion library. Three records are easier to dispute than a generated suite that nobody can read in one sitting. Keep each call identifier stable so a reviewer can map one golden file to one row in the later decision table.

[
  {"id": "coupon-then-tax", "cart": {"subtotal": "20.00"}, "coupon": "0.10", "refund": "0.00"},
  {"id": "zero-after-coupon", "cart": {"subtotal": "0.00"}, "coupon": "0.10", "refund": "0.00"},
  {"id": "refund-once", "cart": {"subtotal": "20.00"}, "coupon": "0.10", "refund": "5.00"}
]

Run the record step on the unchanged function, and commit the golden files before you open a cleanup branch. The check step then becomes the only executable gate that can approve a later structural edit safely. Store both commands in the module README only after a teammate can run them from a clean checkout. Parse money strings to Decimal inside the test adapter, or the golden files will pin binary float noise instead of cents.

python -m adjuster_characterize record --calls calls.json --out golden/
python -m adjuster_characterize check --calls calls.json --golden golden/
git diff --name-only main...HEAD

Keep the first edit inside the recorded lines

The smallest safe change, in this example, is extracting tax rounding into a pure helper while coupon and refund logic stay put. That extraction is safe only when the three golden files still match and the diff does not touch an unrecorded module. A rename of the audit writer, or a move of refund math, is a second change and waits for its own record.

# proposal: smallest safe extraction, not executed for this article
from decimal import Decimal, ROUND_HALF_UP

def round_tax(taxable: Decimal) -> Decimal:
    return taxable.quantize(Decimal("0.01"), rounding=ROUND_HALF_UP)

The helper accepts a decimal taxable amount and returns a half-up cent, with no cart mutation inside it. Coupon percentages and refund subtraction remain in the original function until a later budget records them alone. That split is the whole structural change the first patch is allowed to contain under this budget.

Reviewers can apply a simple blast-radius rule without opening a style argument about names or file layout. If git diff --name-only lists a file that no recorded call executes, the patch is too wide for this budget. If the check command prints a call id, the edit changed behavior and is no longer a cleanup. The shell fragment below is a proposal, and it treats any path besides the characterized file as a failed budget.

# proposal: fail review when a changed path sits outside the characterized file
git diff --name-only main...HEAD > changed.txt
grep -vx 'billing/adjuster.py' changed.txt && echo 'patch too wide' && exit 1
python -m adjuster_characterize check --calls calls.json --golden golden/

The grep step prints every changed path that is not the characterized file, and a nonempty result means the patch is too wide. Run the characterization check only after that path list is empty, so a behavior failure is not confused with an oversized diff. Label this script as a review aid, because a rename of the characterized file would otherwise look like an oversized patch.

Review decision table

Observed signal	Review action
Golden files match, and the diff stays inside the characterized function	Accept the single extraction
Golden files match, but the diff edits an unrecorded helper	Reject the patch and ask for a smaller diff
Any recorded call fails	Stop and restore behavior before discussing structure
A draft adds calls that nobody has executed on current code	Label them as proposals and exclude them from the gate

Where a free assistant fits, and where it does not

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

MonkeyCode's free model access is useful here as a drafting aid for candidate call descriptions, not as a source of expected totals. You can paste the current function and ask for three input combinations that exercise coupon, zero, and refund branches. You still generate expected JSON by running the unchanged function, because a model can invent a cent that the production code does not return. A free server option fits the check command, since a clean environment avoids pinning a laptop path, a local time zone, or an editor-installed package.

Neither option replaces the golden-file gate, and this article does not claim a named model, a token quota, a hardware size, or a lasting availability window. Readers who lack a clean checkout can try that free server option while the golden-file check remains the only merge gate. Skip the assistant entirely when the function is short enough to record by hand in a single review sitting.

A failure you should expect on the first check

The first check often fails because the golden file captured a datetime string or a random audit identifier. Strip those fields in the recorder, or replace them with a fixed clock and a fixed identifier before you commit the files. A failure that mentions only the payable total is a behavior change, and it should block the extraction rather than refresh the golden file. Updating the golden file in the same commit as the extraction hides the drift this budget was built to catch.

Limitations and who should skip this

This approach pins observed behavior, and it does not prove that the observed behavior is legally or financially correct. A tax bug that already ships will be preserved on purpose until a separate, reviewed correction changes the golden file. Teams that need an audited tax opinion should not treat these three golden files as formal compliance evidence.

The runner also assumes you can call the function without sending a real payment or writing to a shared production table. If the audit insert cannot be intercepted, stop and wrap that write before you record any golden file. People who need a one-pull-request rewrite of the whole checkout flow should not use a three-call budget. The budget will reject that rewrite by design, which is the intended outcome rather than a tooling failure.

Model-drafted expected values are the wrong input for this gate, even when the draft looks precise. A hand-written expected total is also wrong unless it was produced by the unchanged function on the same inputs. If you cannot rerun the current function, you do not yet have a characterization record and should not edit.

What to merge first

Merge the golden files and the unchanged function in one commit, with no structural edit attached to that commit. Open a second commit that extracts only tax rounding, and require a clean check plus a name-only diff that stays inside the characterized file. Leave coupon stacking, refund ordering, and module splits for later budgets that carry their own recorded calls. That sequence is slower than accepting a six-file cleanup, and it still has an executable answer when the assistant layout is wrong.

Pin Duplicate-Delivery Receipts Before You Extract a Webhook Alias

Dakota Wu — Thu, 08 Oct 2026 09:37:57 +0000

Consider a billing module that verified webhook signatures, parsed event JSON, and inserted a ledger row for every accepted delivery. During a routine cleanup, the verifier moved into a new file while duplicate detection stayed in the old one. A replayed event then inserted a second ledger row, because the new boundary never received the prior event id. Treat that replay as an illustrative composite for the workflow below, not as a measured incident from this account.

What actually broke

The failure was not a weak signature algorithm, and it was not a missing unit test for a happy path. Callers already relied on a quieter duplicate contract whenever the provider retried the same event id. An extract can keep every crypto check green and still break that contract at the new function boundary. That is why the first artifact is a receipt row, not a fresh package layout or a renamed client class.

Three rules worth pinning

Production logs for this kind of module often show three rules that no README states in a checkable form. A repeated event id must return the first outcome and must skip a second ledger write. Signature header names can arrive under more than one alias, and only a known alias may pass. Raw body bytes are hashed before JSON parsing, so key order must not change the stored receipt.

Those rules describe current behavior, not a claim that the behavior is the desired long-term design. A characterization pin freezes those rules so a later cleanup can change exactly one rule on purpose. If finance still sends an older alias, record that alias in the pin before anyone deletes the accepting branch.

Receipt rows before any move

Keep the first suite to four fixtures, and give each fixture one receipt row with four fields. Store the event id, the alias that matched, the SHA-256 of the raw body, and an outcome label. Use the labels accepted, duplicate, and rejected, and do not invent a fourth label until a log line requires it. Four rows are enough to reject an extract that drifts, and a larger harness can wait for a real fifth case.

Use the fixture set below for this pass, and do not widen that set while the alias extract is still open.

A valid delivery with the primary signature alias and an event id the process has not seen.
The same raw bytes and the same event id sent again, which must remain a duplicate.
An unknown alias that must be rejected without inserting a ledger row or growing the seen-set.
A known alias whose signature fragment does not match the raw body hash prefix.

Add a fifth row only after an incident shows a behavior these four fixtures do not already cover. Until that incident exists, extra rows mostly add review noise and hide the contract you meant to protect. If two incidents describe the same alias mismatch, extend the existing row instead of opening a second fixture file. The goal is a stable pin for this extract, not a growing archive of one-off provider quirks.

Proposed artifact

The Python below is a proposed, unexecuted example for a fictional ledger webhook, not a log of a real outage. It is not a measured run, not a production verifier, and not a report of customer traffic. The signature compare is a toy prefix check so the example can run without a vendor secret. Replace that compare with your real check only after the receipt fields are already pinned on the old path.

# proposed and unexecuted: pin receipts before moving code
import hashlib
from dataclasses import dataclass

ALIASES = ("x-signature", "x-ledger-signature")

@dataclass(frozen=True)
class Receipt:
    event_id: str
    alias_used: str
    body_sha256: str
    outcome: str

def receipt_for(headers, body: bytes, seen: set[str]) -> Receipt:
    alias = next((name for name in ALIASES if name in headers), "")
    digest = hashlib.sha256(body).hexdigest()
    event_id = headers.get("x-event-id", "")
    fragment = headers.get(alias, "") if alias else ""
    if not alias or fragment != digest[:16]:
        outcome = "rejected"
    elif event_id in seen:
        outcome = "duplicate"
    else:
        seen.add(event_id)
        outcome = "accepted"
    return Receipt(event_id, alias, digest, outcome)

def test_duplicate_preserves_first_outcome():
    seen: set[str] = set()
    body = b'{"amount":10,"currency":"USD"}'
    headers = {
        "x-event-id": "evt-7",
        "x-signature": hashlib.sha256(body).hexdigest()[:16],
    }
    first = receipt_for(headers, body, seen)
    second = receipt_for(dict(headers), body, seen)
    assert (first.outcome, second.outcome) == ("accepted", "duplicate")
    assert first.body_sha256 == second.body_sha256
    assert first.alias_used == "x-signature"

Store expectations outside the assertion

Keep fixtures beside the test so a reviewer can open one directory and see every pinned byte. Store raw bodies as files, store headers as JSON, and keep expected receipts in a table the test loads. Do not recompute the expected hash inside the assertion when a stored digest can sit beside the body file. A stored digest makes a parser that reorders keys fail the pin, which is the drift you want to notice.

# proposed and unexecuted: load stored receipts, do not rebuild them in the assert
import json
from pathlib import Path

def load_cases(root: Path):
    rows = json.loads((root / "expected_receipts.json").read_text())
    for row in rows:
        body = (root / row["body_file"]).read_bytes()
        headers = json.loads((root / row["headers_file"]).read_text())
        yield headers, body, row["receipt"]

{
  "body_file": "evt-7.body",
  "headers_file": "evt-7.headers.json",
  "receipt": {
    "event_id": "evt-7",
    "alias_used": "x-signature",
    "outcome": "accepted"
  }
}

How to run the pin

Run one quiet pytest command, and treat any red assertion as a contract question rather than a prompt to edit the expected tuple. If the current module accepts an alias the test rejects, update the fixture from a captured request before you judge the extract. Reviewers should diff receipt fields, not the whole module, when they decide whether this pass may merge. A green run means these four observations still hold, and it says nothing about SQL, retries, or dashboard copy.

mkdir -p proposed/fixtures
python -m pytest proposed/test_delivery_receipts.py -q --tb=short

How to read a failing receipt

A failing body hash means the bytes changed, or the hash moved onto parsed JSON instead of the raw input. A failing alias means the extracted function consulted a different header map than the fixture recorded. A failing outcome, with hash and alias still equal, usually means duplicate memory never crossed the new boundary. Fix the wiring that dropped the seen-set before you touch backoff numbers, SQL, or operator-facing error text.

Smallest safe extract

After the four receipts pass against the old module, move only the alias tuple into a new file. Leave hashing, the seen-set, and the ledger write in the original function for this pass. The new module exports the tuple and does not import the database, the JSON parser, or the logger. Name the new file for the table it holds, so reviewers do not expect a full client move.

# proposed and unexecuted: smallest extract is the alias table
SIGNATURE_ALIASES = ("x-signature", "x-ledger-signature")

Point the old function at that tuple, then rerun the same four receipts without editing assertions. If the receipts match, stop the pull request there and write the follow-up as a separate change. A second pass may move the hash compare, but only after a mismatched-digest row is already in the pin. One exported tuple is a reviewable diff, while a relocated verifier plus a new retry loop is not.

This sequencing is deliberate scope control, not a claim that alias tables are the hardest part of webhook code. The hard part is knowing which behavior you promised not to change while the file is still messy. Keep the promise in the receipt table, and let the diff stay smaller than the module you are trying to leave behind. A reviewer should be able to explain this pass in one sentence without mentioning the database at all.

Where a separate host fits

Teams sometimes want a second machine for the first characterization run so the laptop that holds deploy keys is not also the test host. MonkeyCode offers free model access and a free server option for drafting redacted fixture rows and running this pytest file. Disclosure: This article was prepared as part of MonkeyCode's product outreach. This article does not state a token quota, a model name, a hardware shape, or a benchmark.

Those details belong in the current product documentation, and they can change without notice to this post. Paste any model draft beside the receipt table, and do not treat the draft as a captured request. Accept a new row only when a human can match its alias and outcome to a log line or a saved request. If those fixtures already live in git, the same free access and free server option can host this first off-laptop run.

Check the current limits in the product documentation before you depend on that run for a merge. Do not send signing secrets, live customer bodies, or unredacted payment identifiers to a hosted runner or a model prompt. The example above uses a fake event id, and a real verifier should stay on systems your policy already allows. A free server is a place to run the pin, not a place to terminate live provider webhooks.

Scope lock

Observation	Pin in this pass	Leave for a later pass
Duplicate event id keeps the first outcome	Yes	No
Which signature alias matched	Yes	No
Raw body hash recorded before JSON parsing	Yes	No
Ledger SQL and account mapping	No	Yes, after receipts stay green
Retry delays and backoff numbers	No	Yes, unless a fixture already encodes them
Operator-facing text for rejected events	No	Yes

If a requested edit is not in the pin column, it does not belong beside the alias extract. Split that edit, or the receipt suite can no longer tell you which change broke the row. The table is a review tool, not a ranking of which subsystem is more important to the business. Use it in the pull request description so the next reviewer does not reopen ledger SQL in this same diff.

Limitations and who should skip this

A pin preserves current behavior, including behavior that a later ticket may correctly call a defect. If the seen-set is only process memory, a duplicate after restart can still write a second row. This four-row test will not catch that gap, because both calls share one in-memory set. Fixing persistence is a separate change with its own fixture, not a drive-by edit inside the alias extract.

Skip the workflow when you have no captured request and would be inventing the contract from memory. Skip it when an external contract suite is already authoritative and your team treats that suite as the merge gate. Also skip a hosted runner when policy forbids third-party execution of repository code, even for a four-row file.

Model output is only a hypothesis generator, not a witness of what production actually sent last week. A draft can add a header that never arrived, or it can repair a duplicate path you meant only to record. The receipt comparison decides whether this pass may merge, and a fluent model explanation does not.

Review checklist

Confirm each fixture came from a captured request or a log line, not from a model guess alone.
Confirm the duplicate fixture reuses the same event id and the same raw bytes as the first delivery.
Confirm the unknown-alias fixture expects rejected and asserts that the seen-set did not gain an id.
Confirm the pull request diff touches the alias tuple and its import, not the ledger write.
Confirm the pytest command in the change note is the same file that holds the four receipts.

What to merge this week

Write down the event id, the matched alias, the raw body hash, and the outcome label for four fixtures. Run that pin on the untouched module, extract only the alias tuple, and rerun the same assertions unchanged. Open the next cleanup only after that second run matches, even if the diff looks too small to matter. A small diff is the intended result when characterization comes first and the extract stays inside one seam.

Pin Absent, Empty, and Null Before You Extract a Settings Overlay

Dakota Wu — Thu, 08 Oct 2026 07:02:39 +0000

Picture a billing worker that skipped invoice generation after a weekend deploy because a blank region string replaced a valid environment value. In that scenario, the on-call engineer expected missing keys and blank values to behave the same way under overlay. They did not, and the same function treated a JSON null as an explicit delete of that key. File reads, environment scans, and CLI parsing lived in one module, so a broad cleanup looked useful and unsafe.

The notes below describe a characterization-first path for that class of settings merger, using a labeled composite module. Nothing in this draft reports a private employer incident, a measured outage length, or any customer count. The tests pin today's behavior before anyone moves code, including behavior that a later change may deliberately reject. Product assistance appears only after that contract exists, and the outreach disclosure sits beside the first mention.

What must stay stable during the extract

A safe extract preserves outputs for every input class you can name, even when those outputs look wrong. The merger currently walks sources in file, environment, then CLI order, and later writes replace earlier writes. A null value deletes the key, while an empty string, zero, and an empty list remain stored values. Moving I/O, renaming keys, and fixing null handling in the same diff would hide which edit changed behavior.

Decision table before any code move

Lock the contract in a table before you touch the module, because prose arguments drift during review. Each row names three source states and the exact merged result you observed, not the result you prefer. You should record absent keys, empty strings, JSON null, numeric zero, and empty collections as distinct states. If two reviewers disagree on a row, rerun the current function and paste the observed output into the table.

Case	File value	Env value	CLI value	Observed merge
later value wins	region=us	region=eu	absent	region=eu
empty string wins	region=us	region=empty string	absent	region=empty string
null deletes	region=us	region=null	absent	region absent
zero is kept	retries=3	retries=0	absent	retries=0
empty list kept	tags=[a]	tags=[]	absent	tags=[]
cli null deletes	region=us	region=eu	region=null	region absent
delete then set	region=null	region=eu	absent	region=eu

Composite module under test

Label this module as an unexecuted teaching example until you paste it into a scratch repository and run it. It intentionally keeps the awkward rules so the tests describe the code you have, not the code you want. Do not import production secrets, live endpoints, or customer fixtures into this small characterization harness at all. The function accepts plain dictionaries so characterization does not depend on disk layout or the process environment.

Messy function to pin

# scratch/overlay.py
# Labeled composite. Run it before you treat any row as evidence.

def overlay_settings(file_cfg, env_cfg, cli_cfg):
    merged = {}
    for source in (file_cfg, env_cfg, cli_cfg):
        for key, value in source.items():
            if value is None:
                merged.pop(key, None)
            else:
                merged[key] = value
    return merged

Characterization tests that refuse silent drift

These tests call the current function and compare full dictionaries, because a partial assert can miss deleted keys. A missing key and a stored null are different outcomes, so the expected object must not contain a placeholder. Keep one assertion per case name, and let that case name match the corresponding decision table row. If a test fails on the first run, fix the expectation to match observed output before you edit production code.

# tests/test_overlay_characterize.py
import pytest

from overlay import overlay_settings

CASES = [
    ("later_value_wins", {"region": "us"}, {"region": "eu"}, {}, {"region": "eu"}),
    ("empty_string_wins", {"region": "us"}, {"region": ""}, {}, {"region": ""}),
    ("null_deletes", {"region": "us"}, {"region": None}, {}, {}),
    ("zero_is_kept", {"retries": 3}, {"retries": 0}, {}, {"retries": 0}),
    ("empty_list_kept", {"tags": ["a"]}, {"tags": []}, {}, {"tags": []}),
    (
        "cli_null_deletes",
        {"region": "us"},
        {"region": "eu"},
        {"region": None},
        {},
    ),
    ("delete_then_set", {"region": None}, {"region": "eu"}, {}, {"region": "eu"}),
]


@pytest.mark.parametrize(
    "name,file_cfg,env_cfg,cli_cfg,expected",
    CASES,
    ids=[row[0] for row in CASES],
)
def test_overlay_characterizes_current_contract(
    name, file_cfg, env_cfg, cli_cfg, expected
):
    del name  # parametrize ids already label the failure
    assert overlay_settings(file_cfg, env_cfg, cli_cfg) == expected

Commands for a local proof

Run the suite from a clean shell so inherited variables do not masquerade as deliberate environment input. The sample function does not read the process environment, but the next extract might, and the habit should start now. Save the command output with the commit that introduces the tests, because a later green run is not the original evidence. If your laptop shell exports REGION or RETRIES, the clean-server rerun described later is the stricter check.

python -m venv .venv
. .venv/bin/activate
python -m pip install pytest
env -u REGION -u RETRIES python -m pytest -q tests/test_overlay_characterize.py

python -c 'from overlay import overlay_settings; print(overlay_settings({"region": "us"}, {"region": None}, {}))'
python -c 'from overlay import overlay_settings; print(overlay_settings({"region": "us"}, {"region": ""}, {}))'

git diff --stat -- overlay.py tests/test_overlay_characterize.py
git diff -- overlay.py

Smallest safe change after the pin

The smallest safe change extracts the loop body into a pure helper and leaves file, environment, and CLI loading untouched. Callers still pass three dictionaries in the same order, and null still deletes while empty strings still overwrite. That boundary is one function move plus an import update, which a reviewer can check against the unchanged test file. A second change may later redefine null, but only after the table marks those rows as intended breaks.

def apply_source(merged, source):
    for key, value in source.items():
        if value is None:
            merged.pop(key, None)
        else:
            merged[key] = value
    return merged


def overlay_settings(file_cfg, env_cfg, cli_cfg):
    merged = {}
    for source in (file_cfg, env_cfg, cli_cfg):
        apply_source(merged, source)
    return merged

What not to smuggle into the move

Adding deepcopy, sorting keys, or coercing empty strings to null would change observable results for some rows. Shared mutable values remain part of the current contract until a test proves callers rely on isolation. Sorting keys would change JSON dump order if a later caller serializes the dict without an explicit sort. Leave those ideas in a follow-up list, and keep their code out of this characterization-backed diff.

Review checklist before merge

Confirm every decision-table row has a passing test whose expected value came from a run, not from a design discussion.
Confirm the diff does not add file reads, environment reads, or argument parsing inside the new helper.
Confirm falsy values other than null, including zero and empty collections, still survive a later source write.
Confirm a planned behavior change is absent from this commit, or is listed as an explicit failing-test follow-up.

Where free model access and a free server fit

Once the table and tests exist, MonkeyCode's free model access can propose extra rows that your first pass missed. Disclosure: This article was prepared as part of MonkeyCode's product outreach. The operator supplied two availability claims for this draft: free model access, and a free server option for running work away from a laptop. This article does not name models, token quotas, hardware sizes, time limits, or benchmark scores, because those details were not verified here.

How to use the assistant without letting it rewrite the contract

Ask for candidate rows only, and require each proposal to cite a source cell and an expected dictionary. Reject any suggestion that corrects null into a stored value, unless you opened a separate behavior-change task. Paste accepted rows into the test file yourself, then run the suite, because an unrun suggestion is not evidence. Treat the open-source project as a helper for drafting and execution, not as a source of production truth.

Why a free server rerun matters for this bug

Environment leaks are part of the original failure mode, so a second run on a machine you did not customize is useful. A free server option lets you repeat the same pytest command outside a shell that already exports billing variables. Record the image or setup notes you can actually verify, and do not assume the remote box matches production libc, locale, or timezone.

If the remote result differs from the laptop result, stop the extract and reconcile the inputs before you trust either green log. If the characterization table is already green locally, one remote rerun is enough of a second opinion before you merge the helper. Keep that remote log next to the test file so a reviewer can see which command produced the green result.

Limitations and who should not use this path

This path assumes you can execute the current function on synthetic dictionaries and read stable, comparable outputs. Skip it when the merger calls a live network, a paid vendor, or a database you cannot stub without changing behavior. Also skip it when product policy already demands a null-semantics change in the same release, because characterization-then-extract would delay a required break. Free model access can invent plausible rows that never occur in your payloads, so every accepted row still needs a local run.

A free server option is a cleaner shell, not a production replica, and unverified hardware claims would only add false confidence. Do not use the remote run as evidence if you cannot record which command you executed and which test file you copied. Teams without permission to upload even synthetic fixtures should keep the suite on an approved internal runner instead. If you cannot explain absent, empty, and null to a reviewer in one table, you are not ready to extract the helper.

What this workflow deliberately leaves undone

The extract does not choose a new precedence policy, and it does not migrate callers to a typed settings object. It also does not prove thread safety, file encoding, or comment-preserving YAML edits, because those risks sat outside the pinned contract. A later change can replace null-delete with store-null, but it should flip specific table rows and show the red tests first. Until that change exists, the honest description of the system is the table you ran, not the overlay you wish you had.

Cap the First Extract at One Stable Seam

Dakota Wu — Thu, 24 Sep 2026 19:53:44 +0000

A billing repository kept refund pricing and audit writes inside one function that had grown past six hundred lines. Two cleanup pulls had already renamed helpers, and each of those pulls shifted partial-refund rounding by one cent. The happy-path tests stayed green because they asserted only the returned total and ignored collaborator sequence. This worked example shows how to pin that sequence before anyone accepts the smallest extract from the function.

The failure mode is an unrecorded seam

Cleanliness is a weak acceptance signal when one function hides several collaborators behind ordinary local calls. A rename can look safer than a behavior change, yet the call sequence can still move underneath the new names. Reviewers then trust the tidier shape and miss a pricing defect that appears only on partial refunds. The characterization step should record collaborator order before the team discusses names, comments, or file splits.

An invocation-order oracle is narrower than a golden snapshot that freezes the entire refund response payload. It answers one question, which is which collaborator ran, and in what sequence, for a single fixture. It does not prove amounts, taxes, or database writes, so those checks remain in separate tests. The narrowness is intentional, because a wide oracle often tempts a large rewrite inside the same change.

Build a seam inventory before touching code

Start by listing seams the function already crosses, using only collaborator names that exist in the current module. You should postpone any proposed replacement architecture while this inventory of existing seams is still incomplete. The inventory should name each collaborator, the input that matters, and whether call order is part of the contract. If the order looks accidental, mark that row unstable and refuse to assert it in the first test.

Seam	Collaborator	Order stable?	Safe to extract now?
Price partial refund	`pricing.quote`	Yes, before audit	Yes, behind current call
Write audit row	`audit.append`	Yes, after quote	No, leave in place
Load tax table	`tax.lookup`	No, cache dependent	No, characterize later
Notify ledger	`ledger.emit`	Unknown	No, needs a separate trace

How to read the inventory

The table is a decision aid for this example, not a measurement taken from production traffic. Fill the stable column from a test run that you execute, rather than from a model guess. If a row remains unknown, that seam stays outside the first diff and waits for its own trace. The first extract may include only the single row that the inventory marks safe to move.

An unexecuted order recorder

The Python below is a proposal for a characterization test, and this article has not executed it. Adapt the import paths to the module you actually own before you treat the assertion as evidence. Keep the recorder inside the test tree so that production code does not gain a tracing dependency. The sample still calls the real pricing function, so use it only when that call is safe without live credentials.

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

    def wrap(self, name, fn):
        def inner(*args, **kwargs):
            self.calls.append(name)
            return fn(*args, **kwargs)
        return inner


def test_partial_refund_call_order(monkeypatch):
    recorder = OrderRecorder()
    import refunds.quote as quote

    monkeypatch.setattr(
        quote.pricing,
        "quote",
        recorder.wrap("pricing.quote", quote.pricing.quote),
    )
    monkeypatch.setattr(
        quote.audit,
        "append",
        recorder.wrap("audit.append", lambda *args, **kwargs: None),
    )

    quote.price_refund(order_id="o-19", amount_cents=2500, partial=True)

    assert recorder.calls == ["pricing.quote", "audit.append"]

Commands that gate the extract

Run that characterization file by itself before you open any production diff in the refund module. A focused pytest command keeps unrelated suite failures from diluting the order oracle you just added. If the assertion fails, change the expected order only after you confirm that current behavior is worth preserving.

python -m pytest tests/characterization/test_refund_call_order.py -q
git diff --numstat -- src/refunds/quote.py tests/characterization/test_refund_call_order.py

Spend a diff budget, then stop

The smallest safe change is a budget you set in advance, not a mood you judge after the rewrite. After the order test is green on the unchanged function, allow one extract and then stop. The numbered budget below is a proposal for this example, and you should tighten it when your review bar is stricter.

Touch only the pricing.quote call site and the new wrapper that preserves its current arguments exactly.
Keep the audit.append call in the original function so the recorded order cannot drift during the extract.
Reject the diff when git diff --numstat shows more than forty changed production lines in the refund module.
Reject the diff when any characterization assertion was edited in the same commit as the production extract.
Re-run the order test and the existing amount tests before you ask another person to review the change.

A forty-line cap is an example threshold for this walkthrough, not a universal law for every repository. The point is to decide that cap before you see an attractive rewrite that expands the task. If the extract cannot fit inside the cap, stop and add another characterization row instead of widening the change.

Use a remote scratch session only for the scaffold

MonkeyCode's free model access and free server option can hold scratch work for this scaffold when those options are still offered. Disclosure: This article was prepared as part of MonkeyCode's product outreach.

This draft does not name a model, a token quota, a hardware shape, or a duration, because those details were not verified here. Treat the remote session as a place to draft the recorder and the inventory, then copy the test back for a run you control. Paste the function signature and the collaborator names, and do not paste production credentials or customer payment rows. Ask for a failing characterization test first, and do not ask the session to perform the extract in that same prompt.

When the draft returns, run the commands above yourself and discard any production edit that the session added without review. A free server helps only when it cannot reach your real databases, because a characterization run must not write shared audit rows. Check the current product terms before you rely on availability, because a free option can change after this article is published. Do not treat a model-written assertion as the oracle until a human has compared it with the function that is running today.

If that session cannot run pytest, it is not a substitute for the command step, and you should finish the proof elsewhere. The hosted draft is optional scaffolding, and the acceptance evidence remains the local or CI command output. Remove any generated file that imports unreviewed helpers or widens the diff beyond the single safe seam. A session that offers a full rewrite has left the workflow, even if the prose around that rewrite sounds careful.

Who should skip this workflow

Skip the order oracle when collaborators run concurrently and the sequence is not an actual contract. An assertion on accidental order will fail under load and will train the team to weaken the characterization suite. Skip the method when you cannot execute the legacy function safely, because a recorder that never runs is only fiction. Skip a free remote session when the module handles secrets, payment keys, or personal data you are not allowed to upload.

The same characterization file still works on an offline machine that never contacts a hosted coding session. Also skip the extract when you do not have a reviewer who can reject a diff that exceeds the written budget. Teams that need a multi-seam redesign should schedule that work as a separate effort with its own oracles. This workflow is a poor fit for a release-night patch, because the inventory itself takes a deliberate pass.

Review notes that keep the change small

Write the review comment as a checklist that points at the inventory row, the order assertion, and the numstat result. Ask the author to attach command output rather than describing the refactor with adjectives about clarity. If the expected call list and the observed call list differ, the review stops even when the helper looks cleaner. That rule is what separates a characterization-led extract from a cleanliness pass that happens to include tests.

Quote the inventory row that marks the seam safe, including the collaborator name and the stability judgment.
Quote the expected call list and the observed call list from the characterization run, not a paraphrase of the diff.
Paste the numstat line count for production files and stop the review if that count exceeds the written budget.

What this does not prove

A green order test does not prove correct cents, tax calculations, or idempotent audit writes under retries. Keep those oracles in separate tests, and do not fold them into the first commit that moves a collaborator. The inventory table does not rank architectural quality, and it should not be cited as a performance or cost result. It also does not authorize a second extract, a rename sweep, or a comment rewrite in the same review.

If your team already keeps characterization tests beside messy modules, compare today's free-model and free-server terms with the limits above. Open a remote session only when those terms still match this narrow scaffold job, and keep acceptance on the test run you execute.

Record One Nested Decision, Then Extract a Single Predicate

Dakota Wu — Wed, 23 Sep 2026 16:30:51 +0000

A pricing function still folds region rules, bulk surcharges, and coupon stacking into one nested block. A teammate asks an assistant to tidy that module before a tax change lands next week. The first generated patch rewrites four helpers, renames two exceptions, and flips a surcharge for twelve-item carts. Review then spends more time reconstructing prior behavior than evaluating the one extract that was actually needed.

This walkthrough treats that failure as a process problem rather than a taste debate about clean code. The useful unit of work is one nested decision on one hot path, recorded before any symbol moves. After the outcomes are frozen, the only permitted edit is a single predicate extract that preserves those outcomes. The fixture below is labeled as an unexecuted example; adapt the recorder to your language and runner.

Why broad cleanup patches fail on nested pricing logic

Messy pricing code is usually a decision tree that hides inside mutation, logging, and ad-hoc rounding. Assistants trained to improve readability optimize for local style, not for the sparse matrix of inputs that production actually hits. A four-hundred-line rewrite can look coherent in diff view while changing only one compound condition that finance already depends on.

Three failure patterns show up repeatedly in review, even when the generated code is syntactically nicer:

Silent branch collapse. Two region checks get merged, and a cart that used to skip surcharge now pays it.
Exception reshaping. A ValueError becomes a custom type, and an upstream retry path stops matching.
Rounding drift. Intermediate round(..., 2) calls move, so a twelve-item cart differs by one cent.

None of those failures are visible if the first test you add is an assertion against the new design. Characterization has to lock the old outcomes first, before any helper is renamed or moved. Only then does a one-predicate extract become a reviewable change rather than a behavior lottery.

Freeze the nested decision, not the surrounding module

Pick the hottest path through the function, not the whole file, before anyone starts renaming symbols. In this fixture, that path is whether a cart receives a bulk surcharge and which reason code is attached. Coupon stacking and tax remain inside the messy function on purpose, because moving them would expand the blast radius past a single commit.

Define a record as a triple: canonical input, outcome tuple, and a stable hash of that pair. The hash is a review signal, not a cryptographic control, and a mismatch should stop the extract immediately. If two consecutive runs disagree, the path is still too noisy to touch.

A compact recorder for one hot path

The module under test is intentionally awkward. It mutates a dict, appends a log line, and buries the surcharge predicate among unrelated branches.

# pricing.py — unexecuted fixture, not production code
from typing import Any


def price_order(cart: dict[str, Any]) -> dict[str, Any]:
    items = cart.get("items") or []
    region = (cart.get("region") or "US").upper()
    coupon = cart.get("coupon")
    subtotal = sum(
        float(i.get("unit_cents", 0)) * int(i.get("qty", 0)) for i in items
    )
    log = list(cart.get("_log") or [])

    surcharge = 0.0
    reason = "none"
    count = sum(int(i.get("qty", 0)) for i in items)

    if region in {"EU", "UK"} and coupon == "VATZERO":
        reason = "vat_exempt"
    elif count >= 12 and region != "EU":
        surcharge = round(subtotal * 0.04, 2)
        reason = "bulk_surcharge"
        log.append(f"bulk:{count}:{region}")
    elif count >= 12 and region == "EU":
        reason = "eu_bulk_skipped"
        log.append(f"skip_eu:{count}")
    else:
        log.append(f"std:{count}:{region}")

    if coupon == "SAVE10" and reason != "vat_exempt":
        subtotal = round(subtotal * 0.9, 2)

    cart["subtotal"] = subtotal
    cart["surcharge"] = surcharge
    cart["reason"] = reason
    cart["_log"] = log
    cart["total"] = round(subtotal + surcharge, 2)
    return cart

The recorder ignores style and stores only the decision surface planned for extract: item count, region, coupon, reason, surcharge, and total.

# characterize_price_order.py — unexecuted fixture
import hashlib
import json
from copy import deepcopy

from pricing import price_order

CASES = [
    {"items": [{"unit_cents": 199, "qty": 12}], "region": "US", "coupon": None},
    {"items": [{"unit_cents": 199, "qty": 12}], "region": "EU", "coupon": None},
    {"items": [{"unit_cents": 199, "qty": 11}], "region": "US", "coupon": None},
    {"items": [{"unit_cents": 500, "qty": 12}], "region": "UK", "coupon": "VATZERO"},
    {"items": [{"unit_cents": 199, "qty": 12}], "region": "US", "coupon": "SAVE10"},
    {"items": [{"unit_cents": 50, "qty": 0}], "region": "US", "coupon": None},
    {"items": [{"unit_cents": 199, "qty": 12}], "region": "eu", "coupon": None},
]


def outcome(cart):
    result = price_order(deepcopy(cart))
    return {
        "count": sum(int(i.get("qty", 0)) for i in cart.get("items") or []),
        "region": (cart.get("region") or "US").upper(),
        "coupon": cart.get("coupon"),
        "reason": result["reason"],
        "surcharge": result["surcharge"],
        "total": result["total"],
    }


def ledger_hash(rows):
    blob = json.dumps(rows, sort_keys=True, separators=(",", ":")).encode()
    return hashlib.sha256(blob).hexdigest()[:16]


if __name__ == "__main__":
    rows = [outcome(c) for c in CASES]
    print(json.dumps(rows, indent=2, sort_keys=True))
    print("ledger", ledger_hash(rows))

Commands that keep the freeze honest

Run the recorder twice before anyone edits pricing.py, and treat a hash mismatch as a stop sign. Store the printed ledger in the review notes, or as a checked-in JSON snapshot if that habit already exists. The second run must match the first hash; if it does not, shrink the recorded surface before extracting anything.

python characterize_price_order.py | tee /tmp/ledger1.txt
python characterize_price_order.py | tee /tmp/ledger2.txt
diff -u /tmp/ledger1.txt /tmp/ledger2.txt
python -m pytest tests/test_price_order_characterization.py -q
git add characterize_price_order.py tests/test_price_order_characterization.py
git commit -m "Characterize bulk-surcharge decision before any extract"

A minimal pytest pin is enough for CI. It should fail on reason-code drift, surcharge drift, or total drift, and it should ignore log-line wording.

# tests/test_price_order_characterization.py — unexecuted fixture
from characterize_price_order import CASES, ledger_hash, outcome

# Captured from the first honest run of characterize_price_order.py
PINNED_HASH = "replace_me_after_first_run"


def test_bulk_surcharge_decision_is_frozen():
    rows = [outcome(c) for c in CASES]
    assert ledger_hash(rows) == PINNED_HASH

Replace PINNED_HASH with the value from the first run, then keep that commit separate from the extract commit. Mixing the pin and the extract in one diff reintroduces the original review problem, because reviewers cannot tell a captured baseline from a behavior change.

A decision table the extract must not violate

The table is the contract for the extract commit. If an assistant proposes a prettier predicate that disagrees with any row, the extract is rejected, regardless of naming quality.

qty	region	coupon	reason	surcharge rule
12	US	none	bulk_surcharge	4% of pre-coupon subtotal
12	EU	none	eu_bulk_skipped	0
11	US	none	none	0
12	UK	VATZERO	vat_exempt	0
12	US	SAVE10	bulk_surcharge	4% first; coupon then cuts subtotal
0	US	none	none	0
12	eu	none	eu_bulk_skipped	0, because region is uppercased

The SAVE10 row is the interesting collision in this fixture. The current function applies bulk surcharge against the pre-coupon subtotal, then discounts the subtotal. A cleanup that computes surcharge after the coupon looks cleaner and is wrong relative to today's ledger. Characterization exists to make that disagreement boring and automatic, instead of a late finance incident.

The smallest safe change: one predicate, one commit

After the hash is pinned, the only allowed production edit is extracting the condition that decides bulk_surcharge versus eu_bulk_skipped. Coupon handling, logging, and totals stay in price_order during this commit. VAT exemption stays inline as well, because it is a different decision and deserves a later extract.

def bulk_surcharge_reason(count: int, region: str) -> str | None:
    """Return a bulk-related reason, or None when the bulk branch does not apply."""
    if count < 12:
        return None
    if region == "EU":
        return "eu_bulk_skipped"
    return "bulk_surcharge"

Wire it in with the smallest possible splice. Do not reorder coupon math in the same commit, even if the new order reads more linearly.

    bulk_reason = bulk_surcharge_reason(count, region)
    if region in {"EU", "UK"} and coupon == "VATZERO":
        reason = "vat_exempt"
    elif bulk_reason == "bulk_surcharge":
        surcharge = round(subtotal * 0.04, 2)
        reason = bulk_reason
        log.append(f"bulk:{count}:{region}")
    elif bulk_reason == "eu_bulk_skipped":
        reason = bulk_reason
        log.append(f"skip_eu:{count}")
    else:
        log.append(f"std:{count}:{region}")

Then re-run the recorder and the pinned test before opening the review. If PINNED_HASH still matches, the extract changed structure without changing the nested decision. If it does not match, revert and shrink the splice; do not fix forward by editing cases.

A patch-size budget you can enforce in review

Use this checklist on the extract commit only, not on the earlier characterization commit:

Production diff stays under roughly forty lines, including the new function.
Exactly one new symbol is introduced, and no existing exception type is renamed.
Coupon, tax, and logging branches are untouched except for the call-site splice.
Characterization hash is unchanged; any hash delta blocks merge.
No formatter-only edits in unrelated functions ride along in the same commit.

git diff --stat HEAD~1
git diff -U0 HEAD~1 -- pricing.py
git diff --name-only HEAD~1

If an assistant or a colleague cannot stay inside that budget, split the work instead of raising the budget. The next extract might be is_vat_exempt(region, coupon), and it gets its own pin if those cases are not already covered. Sequential extracts are slower to write and much cheaper to review than one impressive cleanup.

Where a coding assistant belongs in this sequence

Assistants are useful after the ledger exists, because the task becomes proposing a predicate that preserves these rows, not making the file look clean. They are much less useful as the first author of a module-wide rewrite, which is how the twelve-item surcharge usually flips. Feed the model the decision table and the current function, then reject any patch that also reformats coupon math.

Disclosure: This article was prepared as part of MonkeyCode's product outreach. If the recorder needs a scratch environment instead of a laptop checkout, MonkeyCode's free model access and free server option can draft extra cases and rerun the hash loop without pointing the assistant at production secrets. Accept only a predicate-sized patch that keeps PINNED_HASH stable, and keep the same pytest pin in CI regardless of which editor wrote the function.

The method still holds if pytest runs on a workstation and the predicate is written by hand. The assistant is optional infrastructure around a frozen decision, not a substitute for the freeze.

Limitations

Characterization records what the function does today, including bugs that product may later want to change on purpose.
A seven-row table does not cover concurrent carts, currency conversion, or coupons that expire mid-request.
Hashing JSON rows will churn if logs, timestamps, or unordered keys are included without sort_keys.
Extracting a predicate does not improve observability; existing logs still carry production incidents.
Assistants can memorize the table and still reorder surcharge math unless the pin is enforced in CI.

Who should skip this approach

Skip it if the change is an intentional price-policy update rather than a structure-only extract. Skip it if the pipeline cannot run even a single-file pytest target on every patch. Skip it for cryptographic, access-control, or tax-engine code that needs a formal spec, not a snapshot of yesterday's behavior. Skip it when the hot path is not identifiable, because freezing a random nested if teaches the team the wrong boundary.

The durable habit is small and slightly boring. Record one nested decision until its hash is dull, then move one predicate, then stop. The cleanup still happens; it happens as a sequence of reviewable extracts instead of one impressive diff that finance cannot reconstruct.

Weekend Drift in SLA Deadlines: Characterize First, Extract Next-Open Last

Dakota Wu — Tue, 22 Sep 2026 14:51:34 +0000

A support platform asked a coding assistant to tidy a 400-line first-response SLA module last quarter. The assistant produced a calendar package, a smaller public surface, and unit tests that stayed green on synthetic weekdays. Staging then placed Friday 16:55 urgent tickets onto Monday 09:00 instead of Friday 17:00. Production treated 17:00 as inclusive for urgent severity and exclusive for normal severity, inside one nested branch.

Why the tidy extract moved the clock

Cleaner names did not preserve the cutoff table that operators had learned from escalations. The nested branch mixed timezone conversion, holiday lookup, severity multipliers, and weekend rolling in a single return path. Characterization tests would have failed the extract before review, because Friday 16:55 urgent is a known production shape. The lesson is operational rather than stylistic: freeze observable deadlines, then change one seam.

Industry talk about AI-assisted coding often frames the risk as slow skill atrophy for working engineers. For messy calendar code the nearer risk is quieter: a helper extract that inverts one inclusive boundary. Agents optimize for names and structure, while production SLAs optimize for the last minute that still counts. Those two objective functions diverge on Friday afternoons, month-end cutoffs, and company holiday eves.

A reviewer cannot hold every cutoff in working memory while reading a 400-line module. A fixture table can hold them, if the rows come from production-shaped timestamps rather than tidy round hours. The sections below build that table, hash it, and only then extract next-open. The allowed extract is a single next-open function, not a rewrite of the calendar package.

Inventory implicit calendar rules

Do not start from the helpers you wish the module already exposed in production. Start from tickets that already missed or barely met first response in staging logs. Collect a compact rule inventory that a reviewer can check without reading the module. The inventory below is a decision table for characterization, not a proposed redesign.

Convert created_at to America/New_York before any weekday or clock comparison runs.
Treat 17:00 as inclusive for urgent and exclusive for normal on the created local day.
Skip Saturday, Sunday, and dates present in the holiday CSV after the cutoff check.
Open the next business day at 09:00 local if the ticket misses the close window.
Keep month-end and year-end rows, because rolling 31 January can land on a weekend holiday eve.

created_local	severity	holiday_csv	expected seam
Fri 16:55	urgent	no	same-day 17:00
Fri 17:00	urgent	no	same-day 17:00
Fri 17:00	normal	no	Mon 09:00
Fri 16:55	normal	no	same-day 17:00
Sat 10:00	urgent	no	Mon 09:00
Thu 16:00	normal	Fri holiday	Mon 09:00
31 Jan 16:55	urgent	no	31 Jan 17:00 or next open

The table is the contract. Named functions are optional until that contract stops moving under a hash.

Worked example: a tangled first-response deadline

The module below is a compressed stand-in, not a copy of any vendor SLA engine. It keeps several rules in one function so an extract has somewhere real to fail. Treat timestamps, holidays, and expected hashes as fixtures for this article, not as production measurements.

# sla_deadline.py
from __future__ import annotations

from datetime import datetime, time, timedelta
from zoneinfo import ZoneInfo

TZ = ZoneInfo("America/New_York")
OPEN = time(9, 0)
CLOSE = time(17, 0)
HOLIDAYS = {"2026-01-01", "2026-07-03", "2026-07-04", "2026-12-25"}


def first_response_deadline(created_at: datetime, severity: str) -> datetime:
    local = created_at.astimezone(TZ)
    sev = severity.lower().strip()
    close_inclusive = sev == "urgent"

    def is_holiday(d) -> bool:
        return d.date().isoformat() in HOLIDAYS

    def is_weekend(d) -> bool:
        return d.weekday() >= 5

    # Nested on purpose: cutoff, weekend, and holiday share one return path.
    cursor = local
    if is_weekend(cursor) or is_holiday(cursor):
        cursor = datetime.combine(cursor.date(), OPEN, tzinfo=TZ)
        while is_weekend(cursor) or is_holiday(cursor):
            cursor = cursor + timedelta(days=1)
            cursor = datetime.combine(cursor.date(), OPEN, tzinfo=TZ)
        return cursor

    clock = cursor.timetz().replace(tzinfo=None)
    if clock < CLOSE or (close_inclusive and clock == CLOSE):
        return datetime.combine(cursor.date(), CLOSE, tzinfo=TZ)

    cursor = datetime.combine(cursor.date() + timedelta(days=1), OPEN, tzinfo=TZ)
    while is_weekend(cursor) or is_holiday(cursor):
        cursor = cursor + timedelta(days=1)
        cursor = datetime.combine(cursor.date(), OPEN, tzinfo=TZ)
    return cursor

Friday 17:00 urgent stays on Friday. Friday 17:00 normal rolls to Monday 09:00. That single comparison is the defect surface most calendar cleanups rewrite by accident.

Turn the decision table into an oracle

Write fixtures as rows, not as assertions scattered through test names. ISO timestamps keep timezone offsets visible when a later extract starts calling utcnow. The loader below is the characterization suite; it does not claim to be a domain model.

# characterize_sla.py
from __future__ import annotations

import csv
import hashlib
import json
from datetime import datetime
from pathlib import Path

from sla_deadline import first_response_deadline

FIXTURE = Path("fixtures/sla_deadlines.csv")


def load_rows(path: Path) -> list[dict[str, str]]:
    with path.open(newline="", encoding="utf-8") as handle:
        return list(csv.DictReader(handle))


def observe(row: dict[str, str]) -> dict[str, str]:
    created = datetime.fromisoformat(row["created_at"])
    got = first_response_deadline(created, row["severity"])
    return {
        "id": row["id"],
        "created_at": created.isoformat(),
        "severity": row["severity"],
        "deadline": got.isoformat(),
    }


def oracle_payload() -> list[dict[str, str]]:
    rows = load_rows(FIXTURE)
    observed = [observe(row) for row in rows]
    return sorted(observed, key=lambda item: item["id"])


def oracle_hash(payload: list[dict[str, str]]) -> str:
    blob = json.dumps(payload, separators=(",", ":"), sort_keys=True)
    return hashlib.sha256(blob.encode("utf-8")).hexdigest()


if __name__ == "__main__":
    payload = oracle_payload()
    digest = oracle_hash(payload)
    Path("artifacts").mkdir(exist_ok=True)
    Path("artifacts/sla_oracle.json").write_text(
        json.dumps({"sha256": digest, "rows": payload}, indent=2),
        encoding="utf-8",
    )
    print(digest)

Seed the CSV with production-shaped minutes, not only 09:00 and 17:00. Include a Friday 16:55 urgent row, a Friday 17:00 pair, a Saturday create, and a Thursday before a Friday holiday. If the team has sanitized staging exports, prefer those timestamps over invented round numbers.

id,created_at,severity
fr-1655-u,2026-07-10T16:55:00-04:00,urgent
fr-1700-u,2026-07-10T17:00:00-04:00,urgent
fr-1700-n,2026-07-10T17:00:00-04:00,normal
fr-1655-n,2026-07-10T16:55:00-04:00,normal
sat-1000-u,2026-07-11T10:00:00-04:00,urgent
thu-pre-holiday,2026-07-02T16:00:00-04:00,normal

Pin the digest before anyone opens an extract branch. Re-running the oracle on the messy module should print the same SHA-256. Any later candidate that changes a deadline fails the hash even when new unit tests stay green.

python characterize_sla.py
git add fixtures/sla_deadlines.csv artifacts/sla_oracle.json sla_deadline.py
git commit -m "Pin SLA deadline oracle before next-open extract"

Fail the oversized extract on purpose

Label the next block as a rejected candidate, not as a recommended design. An assistant will often replace holidays, timezones, and cutoffs in one commit because the names look related. Run the oracle against that shape and keep the log.

# rejected_calendar_package.py
from datetime import datetime, time, timedelta
from zoneinfo import ZoneInfo

# Proposed rewrite: one close rule for every severity.
CLOSE = time(17, 0)


def first_response_deadline(created_at: datetime, severity: str) -> datetime:
    local = created_at.astimezone(ZoneInfo("America/New_York"))
    if local.timetz().replace(tzinfo=None) <= CLOSE and local.weekday() < 5:
        return datetime.combine(local.date(), CLOSE, tzinfo=local.tzinfo)
    nxt = local + timedelta(days=1)
    while nxt.weekday() >= 5:
        nxt += timedelta(days=1)
    return datetime.combine(nxt.date(), time(9, 0), tzinfo=local.tzinfo)

That candidate collapses inclusive and exclusive 17:00 handling and drops the holiday CSV. The oracle hash moves on fr-1700-u and thu-pre-holiday together. Record both row identifiers in the review note so the extract discussion stays on deadlines, not on taste.

The smallest safe change is next-open

After the oversized rewrite fails, extract only the loop that advances a local datetime to the next business open. Leave cutoff inclusivity inside first_response_deadline until a second oracle row family demands a second seam. The helper below is the entire allowed diff for the first pass.

# next_open.py
from datetime import datetime, time, timedelta

OPEN = time(9, 0)


def next_open(cursor: datetime, is_closed) -> datetime:
    """Advance to 09:00 on the next day that is_closed reports as open."""
    probe = datetime.combine(cursor.date(), OPEN, tzinfo=cursor.tzinfo)
    if probe <= cursor or is_closed(probe):
        probe = datetime.combine(
            (cursor + timedelta(days=1)).date(), OPEN, tzinfo=cursor.tzinfo
        )
    while is_closed(probe):
        probe = datetime.combine(
            (probe + timedelta(days=1)).date(), OPEN, tzinfo=cursor.tzinfo
        )
    return probe

Wire it with a local closure so holiday and weekend rules stay in the original module. Do not pass a new policy object until characterization covers policy changes as their own row family.

from next_open import next_open


def first_response_deadline(created_at: datetime, severity: str) -> datetime:
    local = created_at.astimezone(TZ)
    close_inclusive = severity.lower().strip() == "urgent"

    def is_closed(d: datetime) -> bool:
        return d.weekday() >= 5 or d.date().isoformat() in HOLIDAYS

    if is_closed(local):
        return next_open(local, is_closed)

    clock = local.timetz().replace(tzinfo=None)
    if clock < CLOSE or (close_inclusive and clock == CLOSE):
        return datetime.combine(local.date(), CLOSE, tzinfo=TZ)
    return next_open(local, is_closed)

Re-run the oracle and require a byte-identical digest. If the hash matches, the extract changed structure without changing Friday 17:00. If the hash drifts, restore the nested function and shrink the helper until the digest returns.

python characterize_sla.py
diff -u artifacts/sla_oracle.json <(python -c "import json,characterize_sla as c; print(json.dumps({'sha256': c.oracle_hash(c.oracle_payload()), 'rows': c.oracle_payload()}, indent=2))")

Keep the candidate extract off the oracle machine

Once the oracle is local and hashed, a candidate extract can run somewhere other than a laptop. Disclosure: This article was prepared as part of MonkeyCode's product outreach. MonkeyCode's free model access and free server option can host the candidate while fixtures and hashes stay local. The model may propose the next-open function; the oracle, not the prompt, decides whether the extract is safe. Skip this hosted step when policy forbids sending even synthetic ticket timestamps to an outside service.

A practical split looks like the following command flow, with the digest computed on the machine that already holds staging exports.

# On the oracle machine, never overwrite artifacts/sla_oracle.json from a remote proposal.
python characterize_sla.py > /tmp/local.sha

# On the isolated candidate host, apply only next_open.py and re-run the same fixtures.
python characterize_sla.py > /tmp/candidate.sha

test "$(cat /tmp/local.sha)" = "$(cat /tmp/candidate.sha)"

Do not send the holiday CSV if it includes internal shutdowns that are not already public. Synthetic rows that preserve weekday, minute, and severity are enough for the first extract.

Limitations

This workflow freezes behavior; it does not certify that the behavior is the contractual SLA. Inclusive 17:00 for urgent tickets may itself be a production bug that characterization will faithfully protect. Holiday lists drift every year, and a hash pinned in July will fail in January without a reviewed fixture update. Timezone conversion using America/New_York will not represent teams that store UTC instants and apply business hours in several regions. The next-open helper also assumes civil days, not DST folds around 09:00, so add explicit rows before extracting anything that runs through those nights.

Characterization coverage is only as wide as the CSV. A suite without Saturday creates, holiday eves, and exact 17:00 pairs will bless an extract that later moves those tickets. Agents that generate extra unit tests around the new helper can still miss the production shape if they sample round hours. Keep the oracle in review even when the new tests look thorough.

Who should not use this approach

Skip this method when legal or customer contracts require a designed SLA, not a snapshot of today's messy function. Skip it when the team cannot obtain sanitized timestamps that include Friday close and holiday eves. Skip it when the goal is a multi-region calendar rewrite, because one next-open seam will not carry that change. Skip it when nobody can explain a fixture miss in severity language, because a hash without operators is only a lock on unknown rules.

Teams that lack a staging export should collect twenty real tickets before writing helpers. Teams that already have a documented cutoff table can start from that table and still keep the hash. In both cases the extract remains one function until a second row family fails for a second reason.

After the first green extract

Merge the helper only with the oracle file and the nested cutoff still visible in the original module. Add a review checklist that names the Friday 17:00 pair and the Thursday-before-holiday row. Schedule the next seam, if any, against a new fixture family rather than against a desire for a calendar package. The messy module can stay messy everywhere the hash has not asked for a change.

Tape One Entry Point Before You Extract Anything From a Messy Module

Dakota Wu — Mon, 21 Sep 2026 13:02:12 +0000

A tangled pricing function still mixes tax rules, discounts, and rounding in one seven-hundred-line Python module. An agent then opens a pull request that rewrites helpers, renames locals, and claims the cleanup is behavior-preserving. The existing tests remain green because they only assert a final integer total for two happy-path invoices. This walkthrough freezes one entry point as a contract tape, then allows only the smallest extract that keeps that tape identical.

The method is intentionally narrow. It does not certify the whole service, and it does not bless a large rewrite just because unit tests still pass.

Why green tests still miss the extract

Messy modules usually have tests that pin outcomes, not contracts. An agent can change control flow, drop a rare branch, or replace None with {} while those outcome tests stay green. Reviewers then debate naming while the silent behavior change hides in a helper that used to skip missing keys. A useful freeze therefore records more than the final number.

Record four things for a single entry point, not for the entire package:

argument type trees and sorted mapping keys
return type trees, including None versus empty containers
exception class names on known failure inputs
a short digest of the canonical JSON result

That combination is a contract tape. It is cheaper than a full-suite dump and stricter than one assertion on a total. The tape is the gate; the extract is allowed only after the gate is red-green on the current tree.

The lab fixture

The example below is a proposed fixture, not a production service. Treat every snippet as unexecuted sample code for this walkthrough.

# messy_pricing.py — proposed lab fixture
from decimal import Decimal, ROUND_HALF_UP


def price_invoice(payload):
    items = payload.get("items") or []
    subtotal = Decimal("0")
    for item in items:
        qty = Decimal(str(item.get("qty") or 0))
        unit = Decimal(str(item.get("unit") or 0))
        subtotal += qty * unit
    discount = Decimal(str(payload.get("discount") or 0))
    if payload.get("kind") == "wholesale" and subtotal > 100:
        discount += Decimal("5")
    taxable = subtotal - discount
    if taxable < 0:
        taxable = Decimal("0")
    rate = Decimal("0.08") if payload.get("region") == "west" else Decimal("0.06")
    tax = (taxable * rate).quantize(Decimal("0.01"), rounding=ROUND_HALF_UP)
    total = (taxable + tax).quantize(Decimal("0.01"), rounding=ROUND_HALF_UP)
    return {
        "subtotal": str(subtotal),
        "discount": str(discount),
        "tax": str(tax),
        "total": str(total),
        "flags": payload.get("flags") or {},
    }

The function looks small, yet it mixes defaults, regional tax, wholesale extras, and stringified decimals. An agent can split it into several helpers and still keep total stable on the two cases a sparse test file already covers. The missing risk is a changed flags default, a dropped wholesale bonus, or a different empty-items path.

Build the contract tape

The recorder walks JSON-like values, stores a shape tree, and stores a short digest. Run it against one function only. Do not start by taping every private helper, because that freeze would block the extract you actually want.

# contract_tape.py — proposed walkthrough code
from __future__ import annotations

import hashlib
import json
from pathlib import Path
from typing import Any

TAPE_DIR = Path("tapes")


def shape_of(value: Any) -> Any:
    if value is None:
        return {"kind": "none"}
    if isinstance(value, bool):
        return {"kind": "bool"}
    if isinstance(value, int) and not isinstance(value, bool):
        return {"kind": "int"}
    if isinstance(value, float):
        return {"kind": "float"}
    if isinstance(value, str):
        return {"kind": "str", "len": len(value)}
    if isinstance(value, (list, tuple)):
        return {
            "kind": "list",
            "len": len(value),
            "items": [shape_of(v) for v in list(value)[:8]],
        }
    if isinstance(value, dict):
        keys = sorted(value.keys(), key=lambda k: str(k))
        return {
            "kind": "dict",
            "keys": [str(k) for k in keys],
            "fields": {str(k): shape_of(value[k]) for k in keys},
        }
    return {"kind": type(value).__name__}


def canonical(value: Any) -> Any:
    if isinstance(value, dict):
        return {str(k): canonical(value[k]) for k in sorted(value, key=lambda x: str(x))}
    if isinstance(value, (list, tuple)):
        return [canonical(v) for v in value]
    return value


def digest(value: Any) -> str:
    blob = json.dumps(canonical(value), separators=(",", ":"), ensure_ascii=True)
    return hashlib.sha256(blob.encode("utf-8")).hexdigest()[:16]


def record_call(fn, payload):
    row = {"input_shape": shape_of(payload)}
    try:
        result = fn(payload)
    except Exception as exc:
        row["exception"] = type(exc).__name__
        row["result_shape"] = None
        row["digest"] = None
        return row
    row["exception"] = None
    row["result_shape"] = shape_of(result)
    row["digest"] = digest(result)
    return row

Seed the tape with cases that miss the happy path, not only the two invoices already in unit tests. Wholesale bonus, missing items, and a discount that drives taxables below zero are the usual silent diffs.

# record_tape.py — proposed walkthrough code
import json
import sys
from pathlib import Path

from contract_tape import TAPE_DIR, record_call
from messy_pricing import price_invoice

CASES = [
    {
        "name": "retail_east_empty_flags",
        "payload": {
            "items": [{"qty": 2, "unit": "10.00"}],
            "discount": "1.00",
            "region": "east",
        },
    },
    {
        "name": "wholesale_west_bonus",
        "payload": {
            "items": [{"qty": 12, "unit": "9.50"}],
            "kind": "wholesale",
            "region": "west",
            "flags": {"rush": True},
        },
    },
    {
        "name": "negative_after_discount",
        "payload": {"items": [{"qty": 1, "unit": "3"}], "discount": "9.00"},
    },
    {
        "name": "missing_items",
        "payload": {"region": "west"},
    },
]


def build_tape():
    return {
        "entry": "price_invoice",
        "cases": [
            {"name": case["name"], **record_call(price_invoice, case["payload"])}
            for case in CASES
        ],
    }


def main(mode: str) -> int:
    TAPE_DIR.mkdir(exist_ok=True)
    path = TAPE_DIR / "price_invoice.json"
    fresh = build_tape()
    if mode == "--write":
        path.write_text(json.dumps(fresh, indent=2, sort_keys=True) + "\n")
        print(f"wrote {path}")
        return 0
    if not path.exists():
        print("missing tape; run with --write first", file=sys.stderr)
        return 2
    pinned = json.loads(path.read_text())
    if pinned != fresh:
        print("contract tape drift")
        print(json.dumps({"pinned": pinned, "fresh": fresh}, indent=2))
        return 1
    print("contract tape matched")
    return 0


if __name__ == "__main__":
    raise SystemExit(main(sys.argv[1] if len(sys.argv) > 1 else "--check"))

Commands stay boring on purpose. Write once from the known-messy tree, then check after every extract. If the check is not in CI yet, run it locally before you even open the diff.

python record_tape.py --write
python record_tape.py --check
git add tapes/price_invoice.json contract_tape.py record_tape.py
git commit -m "Pin price_invoice contract tape before extract"

A matched tape means the entry point still accepts the same shapes and still emits the same canonical result. It does not mean the internals are pretty, and it does not mean every caller is covered.

Allow only the smallest safe change

After the tape is pinned, the next move is one extract, not a module rewrite. The candidate in this fixture is the discount block, because it is a closed rule with one extra wholesale branch. Keep price_invoice as the public entry so callers do not move in the same commit.

def apply_discount(subtotal, payload):
    discount = Decimal(str(payload.get("discount") or 0))
    if payload.get("kind") == "wholesale" and subtotal > 100:
        discount += Decimal("5")
    return discount

That is the whole change budget for the first patch. Do not rename flags, do not switch Decimal to float, and do not introduce a pricing class in the same diff. If an agent returns a four-file cleanup, reject it before reading the prose in the pull request.

Use a diff gate so the budget is mechanical. The script below is proposed local tooling, not a required platform hook.

# extract_gate.py — proposed walkthrough code
import subprocess
import sys

MAX_FILES = 2
MAX_NET_LINES = 40


def main() -> int:
    raw = subprocess.check_output(
        ["git", "diff", "--numstat", "HEAD"],
        text=True,
    ).strip()
    if not raw:
        print("no unstaged diff against HEAD")
        return 0
    files = 0
    net = 0
    for line in raw.splitlines():
        added, deleted, path = line.split("\t", 2)
        if path.startswith("tapes/"):
            continue
        files += 1
        if added != "-" and deleted != "-":
            net += abs(int(added) - int(deleted)) + min(int(added), int(deleted))
    if files > MAX_FILES or net > MAX_NET_LINES:
        print(f"extract budget exceeded: files={files} net_lines~={net}")
        return 1
    print(f"extract budget ok: files={files} net_lines~={net}")
    return 0


if __name__ == "__main__":
    raise SystemExit(main())

Accept or reject the agent patch

Observation	Decision	Next step
Tape matches and the diff touches one helper plus the entry function	Accept	Commit, then pick the next closed block
Tape matches but three unrelated files moved	Reject	Ask for a single-function extract
Tape drifts on `missing_items` only	Reject	Restore the empty-items default before any rename
Tape drifts on digest but not on shapes	Reject	A value changed; do not treat it as a style cleanup
Tests pass while the tape is missing	Reject	The suite is too coarse to review an agent rewrite

The table is the review script. It keeps the discussion on contracts and budgets instead of on whether the generated names look tidy.

Where a disposable coding environment fits

Once the tape and the gate exist, an agent is useful only as a proposer of the next one-function extract. It should not be the source of truth for behavior. Disclosure: This article was prepared as part of MonkeyCode's product outreach. MonkeyCode's free model access and free server option can host that record-and-check loop when you want a scratch machine, without turning the tape into a marketing demo.

Keep the workflow local-first either way:

Write the tape from the messy tree.
Ask for one extract that preserves price_invoice.
Run python record_tape.py --check and python extract_gate.py.
Reject any patch that fails either command, even when unit tests pass.

The product mention is optional. The tape still works if you run the same commands on a laptop and ignore every coding agent.

Limitations, and who should skip this

The tape hashes canonical JSON of return values, so unordered sets, timestamps, and randomly allocated identifiers will thrash the digest. Do not use this recorder on those outputs without first stripping volatile fields. Shape trees also stop at eight list items, which is enough for invoice lines in this fixture and too weak for bulk imports.

Skip the method when the entry point is a long-lived process, a GUI loop, or a network client with live clocks. Skip it when you do not own the module, because pinning a tape is still a behavior freeze and can conflict with an active feature branch. Skip it when the real bug is numeric policy, such as rounding mode, because a digest match can still hide a business change if your cases never hit that branch.

The approach also fails closed on purpose. A missing tape is a failed gate, not a reason to trust a large agent rewrite. If the team cannot name four cases that miss the happy path, the extract is not the current problem; the missing cases are.

What this walkthrough actually settles

A messy module becomes safer to touch when one entry point has a replayable contract, not when an agent restyles the file. The smallest safe change is then a single closed helper, reviewed against a tape and a diff budget. If those two checks pass, you earned the next extract. If they fail, the rewrite was a story about cleanliness, not a proof about behavior.

Start a Messy-Repo Extract With a Package Boundary Freeze

Dakota Wu — Sun, 20 Sep 2026 11:12:10 +0000

A billing service sat in one Python package for three years, with forty modules sharing helpers through relative imports and a few public functions that plugins actually called. An agent then opened a cleanup pull request that split billing/ into invoices/, tax/, and ledger/ because the folder names looked more professional. Unit tests stayed green, since they imported private helpers the same way the production code did, and the review looked like a tidy architecture win.

Two days later a plugin loader failed in staging because it still imported billing.totals.summarize. The extract had moved the function, deleted the old module, and left no shim. The tests never imported the public path that operators and plugins used. The repo was not missing tests in general; it was missing a freeze of the surfaces that other code was allowed to depend on.

This article treats that failure as a measurement problem, not a taste problem. The workflow below records package boundaries first, then allows only the smallest extract that those records can prove is quiet. Proposals and sample commands are labeled as such; they are a method you can run, not a claim about any particular production system.

Why green tests still ship a broken extract

AI-assisted refactors fail in messy repositories for a boring structural reason. Agents optimize for local readability, while messy packages encode contracts in import paths, __all__ lists, plugin entry points, and call shapes that no unit test names directly. A suite that only exercises internals will endorse a move that production still treats as a public URL.

Current coding-agent reviews often reward a large tree rewrite because the diff looks decisive. That is the same failure mode as shipping work that looks complete while the observable contract never got pinned. If the only evidence is “tests passed,” you have not measured the extract; you have measured the tests you already had.

A boundary freeze is a cheap characterization layer that sits above those tests. It does not prove the new design is better. It only answers whether the extract changed who can call what, and whether any caller still depends on the old path.

Artifact: freeze the public surface, then budget one change

The artifact is a JSON freeze file plus two tests. One test fails if an unexpected public name, export, or import edge appears. The other test fails if you touch more than one module pair in a single extract. Together they force the smallest safe change: move one symbol, keep a shim, and stop.

Proposed layout:

repo/
  billing/                 # the messy package under study
  tools/freeze_boundaries.py
  tests/test_boundary_freeze.py
  tests/test_change_budget.py
  artifacts/boundary_freeze.json

Step 1 — Inventory names and import edges

The following script is a proposed scanner, not a production crawler. It walks one package, records module-level public names, __all__ when present, and import edges that leave the package. Run it against the current tree before anyone moves files.

# tools/freeze_boundaries.py
from __future__ import annotations

import ast
import json
import sys
from pathlib import Path


def iter_py_files(root: Path):
    for path in sorted(root.rglob("*.py")):
        if path.name == "__pycache__":
            continue
        yield path


def module_name(root: Path, path: Path) -> str:
    rel = path.relative_to(root.parent).with_suffix("")
    return ".".join(rel.parts)


def public_names(tree: ast.AST) -> list[str]:
    dunder_all = None
    names: list[str] = []
    for node in tree.body:
        if isinstance(node, ast.Assign):
            for target in node.targets:
                if isinstance(target, ast.Name) and target.id == "__all__":
                    if isinstance(node.value, (ast.List, ast.Tuple)):
                        dunder_all = [
                            elt.value
                            for elt in node.value.elts
                            if isinstance(elt, ast.Constant) and isinstance(elt.value, str)
                        ]
        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
            if not node.name.startswith("_"):
                names.append(node.name)
        if isinstance(node, ast.Assign):
            for target in node.targets:
                if isinstance(target, ast.Name) and not target.id.startswith("_"):
                    names.append(target.id)
    return sorted(set(dunder_all if dunder_all is not None else names))


def outgoing_imports(tree: ast.AST, self_mod: str, pkg: str) -> list[str]:
    edges: list[str] = []
    for node in ast.walk(tree):
        if isinstance(node, ast.ImportFrom) and node.module:
            target = node.module
            if node.level:
                parent = self_mod.split(".")
                target = ".".join(parent[:-node.level] + ([node.module] if node.module else []))
            if not target.startswith(pkg + ".") and target != pkg:
                edges.append(target)
        elif isinstance(node, ast.Import):
            for alias in node.names:
                if not alias.name.startswith(pkg):
                    edges.append(alias.name.split(".")[0])
    return sorted(set(edges))


def freeze(package_dir: Path) -> dict:
    pkg = package_dir.name
    modules = []
    for path in iter_py_files(package_dir):
        tree = ast.parse(path.read_text(encoding="utf-8"))
        mod = module_name(package_dir, path)
        modules.append(
            {
                "module": mod,
                "public": public_names(tree),
                "imports_out": outgoing_imports(tree, mod, pkg),
            }
        )
    return {"package": pkg, "modules": modules}


def main(argv: list[str]) -> int:
    package_dir = Path(argv[1])
    out = Path(argv[2])
    payload = freeze(package_dir)
    out.write_text(json.dumps(payload, indent=2, sort_keys=True) + "\n", encoding="utf-8")
    print(f"wrote {out} modules={len(payload['modules'])}")
    return 0


if __name__ == "__main__":
    raise SystemExit(main(sys.argv))

Suggested first run:

python tools/freeze_boundaries.py billing artifacts/boundary_freeze.json
git add artifacts/boundary_freeze.json
git commit -m "chore: freeze billing package boundaries before extract"

Commit the freeze on its own. Mixing the inventory with the extract hides which names moved because of the refactor and which names the scanner newly discovered.

Step 2 — Fail the build when the freeze drifts

The characterization test below loads the committed freeze and compares it to a fresh scan. Equality is the point. If a cleanup diff silently drops billing.totals.summarize from the public list, this test is the first red signal, even when unit tests still import a private helper.

# tests/test_boundary_freeze.py
import json
from pathlib import Path

from tools.freeze_boundaries import freeze

FREEZE = Path("artifacts/boundary_freeze.json")
PACKAGE = Path("billing")


def test_public_surface_matches_committed_freeze():
    committed = json.loads(FREEZE.read_text(encoding="utf-8"))
    current = freeze(PACKAGE)
    assert current["package"] == committed["package"]
    assert current["modules"] == committed["modules"], (
        "Package boundary changed. Update the freeze in a dedicated commit "
        "or keep a shim on the old public path."
    )

Step 3 — Enforce a one-pair change budget

Large extracts hide the breaking rename among dozens of file moves. The second test reads git diff --name-only against the freeze commit and allows at most two production modules: the source file and the destination file. Test files and the freeze artifact itself are exempt. This is a process control, not a type system.

# tests/test_change_budget.py
import os
import subprocess
from pathlib import Path

BASE = os.environ.get("BOUNDARY_BASE", "HEAD1")  # set to the freeze commit in CI


def changed_paths() -> list[str]:
    out = subprocess.check_output(
        ["git", "diff", "--name-only", BASE],
        text=True,
    )
    return [line for line in out.splitlines() if line]


def test_extract_touches_at_most_one_module_pair():
    prod = []
    for path in changed_paths():
        p = Path(path)
        if p.parts[:1] == ("tests",):
            continue
        if path.startswith("artifacts/"):
            continue
        if path.startswith("tools/"):
            continue
        if p.suffix == ".py":
            prod.append(path)
    assert len(prod) <= 2, (
        f"Extract exceeded the one-pair budget: {prod}. "
        "Move one symbol, keep a shim, land, then repeat."
    )

In CI, set BOUNDARY_BASE to the freeze commit SHA rather than HEAD1. The sample default is a placeholder so the file stays runnable in a local clone after you substitute the real ref.

Smallest safe change after the freeze is green

Once the freeze is committed and both tests pass on main, an extract is allowed only if it preserves the old public path. The pattern is mechanical:

Add the new module with the moved function and no other edits.
Keep the old module as a one-line shim that re-exports the same name.
Update the freeze in a follow-up commit that records both modules.
Delete the shim only after grep, plugins, and the freeze agree that nothing imports it.

Proposed shim, labeled as an example:

# billing/totals.py — kept until callers move
from billing.ledger.summarize import summarize

__all__ = ["summarize"]

That is a smaller diff than a folder taxonomy. It is also easier to revert, because failure still points at one symbol. If an agent returns a fifty-file “domain split,” reject the patch and ask for the shim form. The freeze file tells you whether the agent complied.

Decision table for the extract

Observation after the candidate diff	Freeze test	Budget test	Action
Public names unchanged, one pair of modules touched, shim present	pass	pass	Land the extract
Public name disappeared, no shim	fail	either	Restore the old path before any further moves
Public names unchanged, twelve files moved	pass	fail	Split the patch until one pair remains
New public names appear without a freeze update	fail	either	Record the names in a freeze-only commit
Only tests and docs changed	pass	pass	Out of scope for this protocol

Use the table during review. Do not argue about folder beauty until the first two columns are green.

Where a coding assistant belongs in this protocol

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

Generating the first freeze by hand is tedious in a forty-file package, and agents are useful for drafting candidate characterization tests from that JSON. They are not useful as the authority that decides the extract is safe. If you try MonkeyCode here, use its free model access and free server option only to propose extra assertions against boundary_freeze.json, then keep the tests that actually fail on a shim-less move.

Treat those drafts as untrusted text until they run. An assistant that rewrites the freeze to match a large cleanup is doing the opposite of characterization. The committed JSON is the spec; the model is a helper that may add cases you forgot, such as __all__ gaps or re-exports hiding behind import *.

Limitations, and who should skip this

The scanner only sees module-level definitions and static import nodes. It will miss dynamically built module names, runtime getattr plugins, C extensions, and public behavior that exists only as CLI flags or HTTP routes. Teams whose real contract is a network schema need a different freeze, built from response fixtures rather than AST names.

The change-budget test can be bypassed by editing many symbols inside the two allowed files. Pair it with a human grep for deleted def names when a “small” file is actually a god module. The method also assumes a single package root. A monorepo with several messy packages needs one freeze per package, or the budget becomes meaningless.

Skip this protocol if you are deleting a prototype that has no external callers, or if you already have an explicit public API package with compatibility tests. Skip it if the goal is a semantic rewrite rather than a move: characterization of names will not catch a tax-rounding change inside a function that kept the same import path. In that case pin outputs, not boundaries.

The useful result is modest. After a freeze exists, a messy-repo extract becomes a sequence of one-symbol moves with shims, each proven against a committed surface. That is slower than a glamorous tree rewrite, and it is the pace at which plugins, operators, and later reviewers can still explain what changed.

Golden-File a Messy Reporter Before You Extract a Status Mapper

Dakota Wu — Fri, 18 Sep 2026 07:27:41 +0000

A weekly order reporter had grown into one 400-line script with three formats and a process-wide cache. Finance still parsed a side CSV by column position, while operators grepped a stdout banner that embedded a local timestamp. Cleanup pull requests kept failing for reasons that looked cosmetic until someone compared the files byte for byte. The useful move was not a repo-wide restyle, but a characterization suite that locked today's messy output and then one extracted mapping function.

This article treats that sequence as a worked example, not as a war story from a named production system. The reporter below is compact on purpose, and the tests are meant to be copied. If an agent later proposes a broader cleanup, the goldens decide whether the diff is still the smallest safe change.

Why inherited reporters punish large cleanups

Messy modules rarely hide a single defect that a rewrite would isolate cleanly. They hide several implicit contracts that nobody wrote down and that downstream tools still depend on.

Typical contracts in a reporter like this include the following load-bearing quirks:

Status aliases that treat "shipped " and "SHIPPED" as the same operator-facing label
A banner line that on-call grep recipes assume will appear on stdout
A sidecar CSV whose column order is positional for a spreadsheet import
A module-level cache that skips rereads when a batch wrapper calls the reporter twice

An agent that tidies the whole file will often normalize whitespace, rename helpers, and rewrite loops inside one diff. Each edit can look locally reasonable in isolation during review. Together they change more contracts than a reviewer can hold in working memory without a snapshot.

What counts as the smallest safe change

Treat the smallest safe change as a diff that satisfies all four of the checks below. If any check fails, split the work rather than arguing that the extra cleanup is obviously harmless.

It alters one named unit, such as a status mapper, and does not touch an I/O path.
Characterization goldens for stdout and sidecar files remain byte-identical after the diff.
Non-determinism is already pinned, including clock, working directory, locale, and cache seed.
Reviewers can explain the diff without opening a second production file for context.

If a proposed extract also trims trailing spaces inside labels, it is no longer the smallest safe change. Record that behavior change as a later ticket with its own expected output. Ship the extract only after the existing goldens stay green without edits.

Phase 1: freeze the messy reporter

The following module is a compact stand-in for an inherited reporter and is intentionally awkward. Do not clean aliases, caching, or banner formatting until characterization is committed and passing.

# order_reporter.py
from __future__ import annotations

import csv
from datetime import datetime
from pathlib import Path

STATUS_ALIASES = {
    "shipped": "Shipped",
    "SHIPPED": "Shipped",
    "shipped ": "Shipped",
    "queued": "Queued",
    "hold": "On Hold",
    "on-hold": "On Hold",
}

_CACHE: dict[str, list[dict[str, str]]] = {}


def load_rows(path: str) -> list[dict[str, str]]:
    if path in _CACHE:
        return _CACHE[path]
    with open(path, newline="") as handle:
        rows = list(csv.DictReader(handle))
    _CACHE[path] = rows
    return rows


def report(path: str, side_csv: str) -> None:
    rows = load_rows(path)
    stamp = datetime.now().strftime("%Y-%m-%d %H:%M")
    print(f"ORDER REPORT @ {stamp}")
    print(f"source={path}")
    written: list[dict[str, str]] = []
    for row in rows:
        raw = row.get("status") or ""
        stripped = raw.strip()
        label = STATUS_ALIASES.get(raw, STATUS_ALIASES.get(stripped, stripped or "Unknown"))
        sku = row.get("sku") or ""
        print(f"{sku}:{label}")
        written.append({"sku": sku, "status": label})
    with open(side_csv, "w", newline="") as handle:
        writer = csv.DictWriter(handle, fieldnames=["sku", "status"])
        writer.writeheader()
        writer.writerows(written)

The mapper already contains a trap that tidy-up diffs love to erase. Lookup uses the unstripped status first and only then the stripped value, so a key with a trailing space can win. Characterization must keep that order, because a later cleanup of .strip() calls will change labels without touching any call site that looks important.

A characterization harness you can run

Pin time, clear the module cache, and capture both stdout and the sidecar file. Compare each captured document against a committed golden rather than against a rewritten expectation in the same commit.

# test_characterize_reporter.py
from __future__ import annotations

import io
from datetime import datetime as real_datetime
from pathlib import Path
from unittest.mock import patch

import order_reporter

FIXTURES = Path(__file__).parent / "fixtures"
GOLDENS = Path(__file__).parent / "goldens"


def _run_report(tmp_path: Path) -> tuple[str, str]:
    source = FIXTURES / "orders.csv"
    side = tmp_path / "side.csv"
    order_reporter._CACHE.clear()
    buf = io.StringIO()
    with patch("order_reporter.datetime") as mock_dt:
        mock_dt.now.return_value = real_datetime(2026, 9, 18, 9, 0)
        with patch("sys.stdout", buf):
            order_reporter.report(str(source), str(side))
    return buf.getvalue(), side.read_text(encoding="utf-8")


def test_stdout_matches_golden(tmp_path: Path) -> None:
    stdout, _ = _run_report(tmp_path)
    expected = (GOLDENS / "stdout.txt").read_text(encoding="utf-8")
    assert stdout == expected


def test_sidecar_matches_golden(tmp_path: Path) -> None:
    _, sidecar = _run_report(tmp_path)
    expected = (GOLDENS / "side.csv").read_text(encoding="utf-8")
    assert sidecar == expected

Use a fixture that exercises aliases, unknown labels, and the trailing-space key:

sku,status
A-100,shipped
B-200,shipped 
C-300,hold
D-400,unknown

Generate goldens once from current behavior, then commit those files as the contract. Do not edit goldens in the same change that extracts a helper, even when the new output looks cleaner to a reviewer.

python - <<'PY'
from pathlib import Path
import tempfile
from test_characterize_reporter import _run_report, GOLDENS

GOLDENS.mkdir(parents=True, exist_ok=True)
with tempfile.TemporaryDirectory() as tmp:
    stdout, sidecar = _run_report(Path(tmp))
    (GOLDENS / "stdout.txt").write_text(stdout, encoding="utf-8")
    (GOLDENS / "side.csv").write_text(sidecar, encoding="utf-8")
print("goldens written")
PY
pytest test_characterize_reporter.py -q

If pytest is not already a project dependency, run the same two equality checks as a short script. The important property is byte equality, not a snapshot library that normalizes whitespace or line endings by default. Platform newline drift will otherwise get promoted into a fake product contract.

Phase 2: extract one mapping function

After both goldens are green on the messy module, extract only the status lookup. Leave load_rows, the banner, the cache, and CSV writing untouched in that commit.

def map_status(raw: str | None) -> str:
    value = raw or ""
    stripped = value.strip()
    return STATUS_ALIASES.get(value, STATUS_ALIASES.get(stripped, stripped or "Unknown"))

Wire the helper into the existing loop with a one-line replacement and re-run the characterization tests immediately. If stdout or the sidecar drifts, revert the extract instead of repairing goldens. Do not fix forward by rewriting snapshots while the helper is still under review.

That extract is the entire first refactor on purpose. Resist adding file-wide type hints, renaming _CACHE, or sorting SKUs, because those edits expand the blast radius. Each of those ideas can become a later ticket with its own golden review once this seam is isolated.

Decision table for later cuts

Keep a short table next to the harness so humans and agents do not bundle obvious fixes once the file is open.

Candidate change	Safe as the next diff?	Why
Extract `map_status` only	Yes	Pure function; existing goldens stay identical
Strip keys inside `STATUS_ALIASES`	No	Changes how `"shipped "` is labeled
Remove the module cache	No	Alters repeated-read behavior in batch wrappers
Drop the banner timestamp	No	Operators grep the line; pin time instead
Reorder sidecar columns	No	Spreadsheet import is positional
Normalize aliases in a later ticket	Yes, after new goldens	That is an explicit behavior change

The table is the review checklist, not decoration. A diff that touches two rows in that table is already larger than the smallest safe change.

Where a disposable agent workspace helps

Generating characterization fixtures by hand is slow when the messy module has many branches and alias keys. A coding agent can propose extra rows for the input CSV after it reads STATUS_ALIASES and the golden-generation script. The reviewer still decides which rows encode real contracts and which rows are synthetic noise.

Disclosure: This article was prepared as part of MonkeyCode's product outreach. MonkeyCode is an open-source coding assistant with free model access and a free server option, and those two properties matter here only as a workspace constraint. The free server is a place to generate fixtures and run the harness without writing goldens into a laptop checkout that already has dirty files. Copy the resulting fixtures/ and goldens/ directories back into review, then discard the session rather than merging an in-place restyle.

The method does not depend on any particular product, and a second local clone with a clean virtualenv works the same way. The agent is optional scaffolding around fixture discovery. The goldens remain the contract that makes the later extract auditable.

Limitations and who should skip this

This approach is a poor fit when behavior is undefined on purpose, such as a prototype that must change daily and has no downstream parser. It is also the wrong tool for cryptographic code, concurrent writers, or modules whose useful output is a GUI rather than text. Golden files freeze encoding and newline details, so they will flake if one machine writes \r\n and another writes \n.

Pin newline="" and UTF-8 at every file boundary, or the harness will encode platform noise as a product contract. Do not use characterization-then-extract as cover for leaving secrets or customer rows in fixtures. Sample CSVs should be synthetic, and if the messy reporter talks to a network, fake the transport before you snapshot anything.

Teams that already have fast unit tests around pure functions do not need this ceremony for those functions. Save it for inherited scripts where tests never existed and the I/O itself is the product that finance and operators still consume.

Close the loop on the first cut

A messy repo becomes safer when the first cleanup diff is boring and easy to revert. Lock stdout and sidecar bytes, extract one mapper, and stop before the file looks tidy. The next implicit contract can wait for its own goldens cycle, including cache behavior and banner format, because those are separate seams. That sequence is slower than a generated restyle, and it is the sequence that keeps a spreadsheet import aligned with what operators still grep in logs.

Build an Environment Ledger Before Cleaning a Tangled CLI

Dakota Wu — Thu, 17 Sep 2026 05:35:13 +0000

A cleanup pull request looked harmless until the nightly invoice job wrote files into the wrong directory. The refactor had replaced os.getcwd() with a packaged resource path, and every relative open() followed it. Tests still passed because they ran from the repository root, which matched the old accidental contract. The failure appeared only on a scheduler whose working directory was /var/lib/batch rather than the checkout.

Messy repositories accumulate these environmental contracts for years without documenting them as interfaces. Coding agents and human cleanups both treat cwd, locale, timezone, and temp directories as leftover implementation details. They are not details when a batch job, a cron entry, or a container WORKDIR already depends on the old accident. The practical sequence is to characterize those surfaces first, then apply the smallest safe change.

Hidden environment contracts in tangled checkouts

Cleanup diffs usually chase names, helpers, and folder structure rather than observable input and output. That bias is reasonable when the module is already a pure function of explicit arguments. Most long-lived scripts are not pure, because they read os.environ, format dates, and write beside the process working directory. An agent that merely modernizes paths can preserve unit tests while changing production file placement.

Three failure modes show up repeatedly in invoice, ETL, and report jobs:

Relative file I/O that silently follows cwd instead of an explicit base directory.
Locale-sensitive decimal separators, month names, and CSV headers that differ under C versus en_US.UTF-8.
Temporary files that land in $TMPDIR on a laptop and in /tmp inside a scheduler image.

None of these outcomes require a malicious model or an unusually large rewrite. They require an unpinned environment plus a cleanup that looks locally smaller than its production effect. Current public debate about agents outgrowing tests is adjacent here: the tests did not shrink, they never observed cwd, locale, or temp placement at all.

What to record before anyone rewrites a module

Treat the process environment as a public API even when the original authors never named it that way. A side-effect ledger is a JSON document that captures the surfaces a later diff is not allowed to change without an explicit decision. The ledger is not a substitute for domain tests; it is a fence around accidental behavior that unit tests rarely exercise.

Record at least the following fields for each entry-point script:

process cwd and the resolved path of every relative open, mkdir, and glob
TZ, LC_ALL, LANG, LC_TIME, LC_NUMERIC, and the locale.getlocale() tuple
tempfile.gettempdir(), TMPDIR, TMP, TEMP, and a sample NamedTemporaryFile prefix
umask, file-creation mode of one artifact, and whether output paths are absolute
a hash of stdout, stderr, and the sorted list of written file paths

Keep secrets out of the ledger on purpose. Redact tokens, connection strings, and customer payloads before the file is committed or copied onto any shared machine.

A proposed characterization harness

The following Python example is a proposed, unexecuted sketch for a small CLI module. It is meant to run against a frozen fixture directory, not against production data. Adjust the command list and fixture layout for the messy repository under review.

#!/usr/bin/env python3
"""Proposed characterization harness for environment-sensitive CLIs."""
from __future__ import annotations

import hashlib
import json
import locale
import os
import subprocess
import sys
import tempfile
from pathlib import Path

LEDGER_VERSION = 1


def read_umask() -> str:
    current = os.umask(0)
    os.umask(current)
    return oct(current)


def snapshot_env(cwd: Path) -> dict:
    return {
        "cwd": str(cwd.resolve()),
        "tz": os.environ.get("TZ"),
        "lang": os.environ.get("LANG"),
        "lc_all": os.environ.get("LC_ALL"),
        "lc_time": os.environ.get("LC_TIME"),
        "lc_numeric": os.environ.get("LC_NUMERIC"),
        "locale": list(locale.getlocale()),
        "tmpdir": tempfile.gettempdir(),
        "tmp_env": {
            "TMPDIR": os.environ.get("TMPDIR"),
            "TMP": os.environ.get("TMP"),
            "TEMP": os.environ.get("TEMP"),
        },
        "umask": read_umask(),
        "python": sys.version.split()[0],
    }


def run_subject(command: list[str], cwd: Path, env: dict) -> dict:
    proc = subprocess.run(
        command,
        cwd=cwd,
        env=env,
        capture_output=True,
        text=True,
        check=False,
    )
    written = sorted(
        str(p.relative_to(cwd)) for p in cwd.rglob("*") if p.is_file()
    )
    stdout_hash = hashlib.sha256(proc.stdout.encode("utf-8")).hexdigest()
    stderr_hash = hashlib.sha256(proc.stderr.encode("utf-8")).hexdigest()
    tree_src = "\n".join([str(proc.returncode), stdout_hash, stderr_hash, *written])
    return {
        "returncode": proc.returncode,
        "stdout_sha256": stdout_hash,
        "stderr_sha256": stderr_hash,
        "tree_sha256": hashlib.sha256(tree_src.encode("utf-8")).hexdigest(),
        "written": written,
    }


def main() -> None:
    fixture = Path("fixtures/invoice_batch").resolve()
    cwd = fixture / "work"
    out_dir = Path("ledgers")
    out_dir.mkdir(exist_ok=True)
    env = os.environ.copy()
    env.update(
        {
            "TZ": "UTC",
            "LC_ALL": "C",
            "LANG": "C",
            "TMPDIR": str(fixture / "tmp"),
        }
    )
    ledger = {
        "version": LEDGER_VERSION,
        "env": snapshot_env(cwd),
        "run": run_subject(
            [sys.executable, "export_invoices.py", "--date", "2026-09-16"],
            cwd=cwd,
            env=env,
        ),
    }
    path = out_dir / "export_invoices.v1.json"
    generated = out_dir / "export_invoices.generated.json"
    generated.write_text(json.dumps(ledger, indent=2, sort_keys=True))
    if path.exists():
        previous = json.loads(path.read_text())
        if previous != ledger:
            raise SystemExit("characterization drift: environment contract changed")
        print("ledger unchanged")
        return
    path.write_text(json.dumps(ledger, indent=2, sort_keys=True))
    print(f"wrote {path}")


if __name__ == "__main__":
    main()

Pin the process environment from the shell as well, because a developer laptop often leaks LANG and TMPDIR into otherwise careful Python. The command below is a proposed isolation wrapper, not a production scheduler definition.

mkdir -p fixtures/invoice_batch/work fixtures/invoice_batch/tmp ledgers

env -i \
  PATH="$PATH" \
  HOME="$HOME" \
  TZ=UTC \
  LC_ALL=C \
  LANG=C \
  TMPDIR="$(pwd)/fixtures/invoice_batch/tmp" \
  python3 tools/env_ledger.py

python3 tools/env_ledger.py
git diff --stat -- ledgers export_invoices.py

A tiny proposed pytest check can fail the build when a cleanup regenerates a different ledger. Keep that test on the committed JSON, and do not overwrite the committed file from CI.

# proposed: tools/test_env_ledger.py
import json
from pathlib import Path


def test_ledger_matches_committed_snapshot():
    committed = json.loads(Path("ledgers/export_invoices.v1.json").read_text())
    generated = json.loads(Path("ledgers/export_invoices.generated.json").read_text())
    assert generated == committed

If the ledger is unchanged and git diff --stat stays inside the intended files, the cleanup remains a candidate. If either check moves, stop and decide whether the new behavior is an intended contract change. Do not refresh the JSON to make a large rewrite look green.

Decision table for the smallest safe change

Use the table below before accepting an agent diff or a human cleanup on a tangled script.

Observation	Allowed next step	Disallowed next step
Ledger matches; diff touches only path constants in one file	Replace cwd-relative opens with an explicit `--base-dir`	Rename modules, extract helpers, or reformat adjacent jobs
Ledger matches; diff also reorders imports and comments	Keep the path change; revert the noise	Bundle style and behavior in one review
Ledger drifts on tmp paths only	Pin `TMPDIR` in the job spec, then retry	Accept "we use tempfile correctly now" without a pin
Ledger drifts on stdout hashes because dates shifted	Freeze `TZ=UTC` and `LC_TIME=C`, then retry	Patch the golden hash to match the new local clock
Ledger drifts on written relative paths	Treat cwd as an API; add a test that `chdir()`s	Continue extracting functions on top of the drift
Diff spans more than one job or shared util	Split the change; re-run the ledger per entry point	"While we are here" refactors across the batch folder

The smallest safe change is the diff that preserves the ledger and touches one contract at a time. Extracting a helper is a second change, even when the helper looks obviously right in isolation. That split is the entire method: characterize, change one surface, re-read the ledger, then stop.

Where a free coding agent belongs in this loop

An agent is useful after the ledger exists, not before the first characterization run. It can propose additional relative-open sites, draft a --base-dir flag, or generate a second fixture that starts in a different cwd. It should not be the process that decides the ledger is stale or that a golden hash deserves a rewrite.

Disclosure: This article was prepared as part of MonkeyCode's product outreach. MonkeyCode offers free model access and a free server option, which is enough to run the harness in a throwaway workspace instead of on a laptop that already holds production exports. That separation matters because characterization fixtures can include path layouts that resemble real jobs even after payloads are redacted.

A practical loop on a free server looks like the following numbered sequence.

Copy a redacted fixture tree, not the production working directory.
Run the ledger command until it writes a stable JSON document.
Ask the model only for the smallest path-explicit change in one file.
Re-run the ledger and inspect git diff --stat before any further prompt.

If the model returns a multi-file rewrite, reject the whole patch and restate the file budget in the next request. Free capacity does not change the review rule; it only keeps the experiment off the machine that mounts customer disks. A throwaway workspace is useful here when the alternative is running fixture trees beside real export directories.

Limitations

This harness does not prove functional correctness of invoice math, tax rounding, or SQL results. It only detects environmental drift that unit tests often miss because they share the developer's cwd and locale. Hashing stdout will fail on intentional logging changes, which then requires a split between semantic output and diagnostic streams. Parallel jobs that race on temporary names need extra pinning, such as a deterministic prefix, or the ledger will flap without a real regression. Container images that reset LANG at entry can disagree with a laptop run even when the Python file itself is unchanged.

The umask field is easy to mis-snapshot if another thread mutates the mask during the run. Treat that field as advisory unless the job creates files whose mode is part of an operational agreement. Do not upload ledgers that still contain customer identifiers in written path names or in captured standard output.

Who should not use this approach

Skip this workflow when the program is already a pure function with injected clocks, paths, and locales. Skip it when the repository cannot provide a redacted fixture and the alternative is copying live data onto a shared server. Skip it for cryptographic code, access-control changes, or anything where a matching stdout hash is the wrong safety property. Teams that already maintain formal acceptance tests should keep those tests, because the ledger is a fence rather than a specification.

Operators who cannot inspect git diff --stat before merge should not delegate cleanup to any model, paid or free. The method assumes a human still owns the environmental contract after the agent returns a patch.

Cleanup diffs fail in production because messy repositories encode cwd, locale, and temp paths as silent APIs. Pin those surfaces with a ledger, allow one contract-preserving change, and only then consider a larger rewrite. A free remote workspace can host the fixture run, but it cannot replace the decision table that keeps the first diff small.