When an AI coding agent changes far more than requested, stop new mutation but preserve the evidence. Do not erase the working tree just to make it look clean. First identify the requested outcome, classify every changed file as necessary, collateral, or unknown, and then rebuild the smallest verified patch from what you can prove.
Freeze the evidence
Capture the current status, diff summary, failing command, and any generated artifacts. If the agent touched an external system, record that state too. Do not deploy, auto-format the whole repository, or start another broad agent run while the evidence is still moving.
This is also a safety boundary. OpenAI’s guidance on running coding agents safely emphasizes limiting access and reviewing consequential actions. Recovery begins by stopping the authority envelope from expanding.
Reconstruct the original contract
Write down four things from the original request:
- the user-visible outcome;
- the files or systems that had to change;
- the invariants that had to survive;
- the checks that would prove completion.
Anything that cannot be connected to one of those points needs evidence before it stays. “The agent thought this was cleaner” is not evidence.
Classify the diff before editing it
Review by behavior, not by file count:
- Necessary: directly enables the requested outcome.
- Supporting: required test, schema, copy, or configuration for that outcome.
- Collateral: formatting, renaming, dependency churn, or refactoring unrelated to acceptance.
- Unknown: potentially relevant, but not yet explained by a test or code path.
Preserve user work and investigate unknowns. Avoid destructive reset commands, especially in a dirty worktree. A clean-looking diff is not worth losing uncommitted work.
Find the smallest trustworthy seam
Trace the real execution path from the user action to the state change. Often the oversized patch exists because the agent solved a guessed architecture instead of the observed path. Add or run one narrow test that reproduces the requested behavior, then keep only changes needed to make that test and its adjacent regression checks pass.
The verification guide for AI-generated code gives a fuller review sequence. If the output is generated, validate the generated artifact—not only the template that produced it.
Verify in widening circles
Use a deliberate order:
- syntax or type check for the changed surface;
- the narrow regression test;
- the affected package suite;
- a real rendered or runtime path;
- repository-wide checks only when the shared impact justifies them.
If a later check fails, do not call the task complete because the narrow test is green. Distinguish a pre-existing failure only with evidence, such as the same failure on the untouched baseline.
Prevent the next oversized change
Future briefs should name protected boundaries, forbidden actions, allowed authority, and completion evidence. Keep the work in small reversible checkpoints. OpenAI’s harness engineering account shows why legible repository feedback matters; the 2025 DORA report on AI-assisted software development is a useful reminder that faster local activity does not automatically improve delivery stability.
SoloMap helps preserve the contract around the change. Keep the intended outcome, current evidence, and acceptance checks in the roadmap step or Solo task, then attach the final verification evidence. This makes scope review about the project’s agreed result rather than about what a long chat happens to remember. The micro-execution loop is designed for that smaller feedback cycle.
Frequently asked questions
Should I revert every AI-generated change and start again?
Not automatically. Preserve evidence and user work first. Keep changes you can connect to the outcome and verify; isolate collateral work instead of erasing the tree blindly.
How do I know whether a refactor is necessary?
Require a concrete dependency: a failing test, an execution-path constraint, or an acceptance criterion that cannot be met without it. Preference alone is not enough.
Can a larger patch still be correct?
Yes, when the behavior genuinely crosses several layers. The issue is not size by itself; it is unexplained scope without traceable evidence.