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.
Top comments (0)