Coding agents:repo repairwith receipts.
A coding agent is not autocomplete with hands. It inspects a repository, forms a bounded plan, uses tools, reads what happened, revises, and hands back evidence.
- SEARCHbefore changing
- PATCHthe smallest surface
- PROVEbefore handing back
AGENTS.mdsrc/export/tests/- inspect→
- plan→
- patch→
- test
2 source files changed
2 checks passed
READY FOR REVIEW ✓Autocomplete proposes code. An agent negotiates with reality.
The useful unit is not “a clever completion.” It is a closed loop: observe the repo, make a bounded change, run something that can disagree, then react to the result.
Nearby text goes in.
const total = items.reduce(…)A plausible continuation comes out. Useful—and then it stops.
NO FEEDBACK LOOPA task meets a living repository.
- 01Read rules + current state
- 02Search for the real change surface
- 03Patch, execute, inspect, revise
- 04Return the diff + evidence + caveats
The output is not the diff. It is the diff plus a reason to believe the diff belongs there.
Turn down the evidence. Watch confidence outrun correctness.
Same task. Same model. One dial changes how much repository evidence the loop may collect. The dial does not add intelligence; it gives reality more chances to disagree.
Keep column order stable. Update relevant tests. Do not edit generated output or unrelated dirty files.
Lower settings cut off observations and checks—not merely “extra polish.”
- 01git status + AGENTS.md
Scope the bay
Find local rules, allowed files, and three unrelated user edits.
- 02rg "owner|csv"
Locate the source
Search connects the schema, exporter, and targeted test.
- 03src/export/csv.ts
Make one small patch
Change the header and source serializer; leave nearby cleanup alone.
- 04pnpm test csv
Let code object
FAIL: row serializer omitted owner. Revise the patch. PASS.
- 05typecheck + git diff
Close the loop
Types pass. Diff matches scope. Hand back checks and caveats.
Targeted tests and typecheck pass; the final diff is inspected; pre-existing dirty files stay untouched.
The loop is the product.
Models propose the next action. The runtime supplies tools, permissions, files, command output, and stopping conditions. Each observation changes what action makes sense next.
- 01INSPECT
Read the shop manual.
Load the task, nearest repository instructions, current worktree state, and relevant project map.
- 02LOCATE
Search before edit.
Trace names, call sites, tests, and ownership until the change surface is evidence—not a filename-shaped hunch.
- 03BOUND
Plan the smallest move.
Name the files, constraints, expected behavior, and checks. Ask before crossing a permission boundary.
- 04PATCH
Change source, not exhaust fumes.
Edit in reviewable increments. Generated files, build output, and vendored code usually have a source upstream.
- 05EXERCISE
Run the closest disagreement.
Start with a targeted test, typecheck, lint, or build that can expose the specific mistake quickly.
- 06HAND BACK
Return proof, not posture.
Inspect the diff. Report what changed, what passed, what was preserved, and what remains uncertain.
A failed check is not the loop failing. It is the loop finally receiving useful information.
A good work order has edges.
The agent can discover implementation detail. It should not have to invent the desired outcome, acceptable blast radius, or definition of done.
“Improve CSV exports.”
- No observable result
- No boundary around adjacent cleanup
- No check that defines “improved”
CSV exports include owner_name after project_name.
Existing column order stays stable; blank owners serialize as empty.
Exporter source + focused tests. Preserve unrelated dirty files.
Do not edit generated clients or change the public schema.
Run export tests and TypeScript checks; report anything not run.
Useful freedom: let the agent discover where the change belongs. Expensive ambiguity: make it guess what success means.
Before touching a bolt.
- 01READ
Read the nearest instructions.
Repository guidance, directory-specific rules, conventions, and requested commands define the local physics.
- 02STATUS
Take a worktree baseline.
Check status before editing. Pre-existing modifications belong to their author; preserve them and avoid accidental bundling.
- 03TRACE
Search through the behavior.
Find definitions, references, tests, schemas, and generators. The first matching file is a clue, not permission to edit.
- 04SMALL
Patch at checkpoint size.
Make one coherent change, inspect the diff, run the closest check, then widen only when evidence requires it.
- 05ASK
Respect the cage.
Sandboxes and approval gates are part of the system. If a command needs more access, explain why and request it—do not route around it.
- 06PROVE
Verify in proportion to risk.
A copy change may need a build. A data migration needs considerably more. “Looks right” is not an executable check.
- observe
- edit one idea
- inspect diff
- run closest check
- record evidence
Six ways the wrench slips.
Most ugly agent failures are not exotic model mysteries. They are ordinary software-process mistakes performed quickly and at scale.
Filename clairvoyance
Smell: Opens the obvious file and edits immediately.
Countermeasure: Search references, tests, and ownership before choosing the change surface.
Generated-file surgery
Smell: Fixes dist/, a generated client, lock output, or compiled assets.
Countermeasure: Find the generator or source-of-truth; regenerate only when the workflow calls for it.
Dirty-tree amnesia
Smell: Treats every existing diff as agent-created—or disposable.
Countermeasure: Baseline status, isolate the requested patch, and name what was intentionally preserved.
The mega-patch
Smell: Mixes the fix, a refactor, formatting, and three acts of personal growth.
Countermeasure: Use small coherent patches. Review and verify before expanding scope.
Permission parkour
Smell: Works around a sandbox, secret, network, or approval boundary.
Countermeasure: Pause, state the blocked action and reason, then request the narrow authority needed.
Green by assumption
Smell: Reports success because the edit looks plausible.
Countermeasure: Run the nearest meaningful check, inspect its output, and disclose checks that could not run.
The model chooses. The runtime makes it real.
“Agent” describes a system, not just a model call. The surrounding runtime decides which files and tools are visible, executes actions, returns observations, enforces permissions, and stops the loop.
function repair(task, repo, policy):
rules = read_nearest_guidance(repo)
baseline = inspect_status(repo)
evidence = search(task, repo)
plan = bound_change(task, rules, evidence)
while plan.has_next_step():
require_permission(plan.next_step, policy)
patch = edit_smallest_source(plan)
result = run_closest_check(patch)
if result.failed:
plan = revise_from(result)
continue
return handoff(
diff=inspect_diff(baseline),
checks=result.passed,
caveats=result.not_run
)
return blocked(reason, next_evidence_needed)Four myths to leave at reception.
“It reads the whole repository.”
Usually it sees selected files, search results, instructions, diffs, and command output inside a bounded context. Good retrieval and inspection still matter.
“More autonomy means fewer checkpoints.”
Longer loops create more opportunities to drift. Small patches and explicit checkpoints make recovery cheaper.
“Passing tests proves correctness.”
Tests prove only the expectations they encode. Review the diff, consider missing coverage, and state caveats.
“The fastest agent makes the biggest patch.”
A smaller change is easier to inspect, exercise, revert, and trust. Throughput without recoverability is expensive theater.