AI Coding Large Repo Recovery Playbook for Teams

When an AI coding run starts slipping in a large repo, most teams make the same mistake. They add more context, ask for a longer run, or escalate straight to a stronger model.

That usually increases the cost before it increases the quality.

A broken large-repo run should be treated like a workflow incident first. The question is not whether the model sounds smart in chat. The question is whether the run can still produce a bounded artifact, survive the real toolchain, and hand off cleanly to the next reviewer.

If you need the upstream explanation for why these runs break in the first place, start with Why AI Coding Agents Fail on Large Repos. This piece starts later in the story. The run is already drifting. Now you need a recovery order that stops the bleeding.

Why random retries usually make the run worse

Large repos punish vague recovery. A retry launched from the same bloated session usually carries forward the same bad assumptions, stale context, and weak verification that caused the failure in the first place.

That is how teams end up paying twice. First for the failed autonomous run, then for the cleanup, review drag, and rediscovery work that follows. If you have read What an AI Coding Task Really Costs, this pattern should look familiar. The expensive part is rarely one model call. It is the churn around a run that never became reviewable.

So the first recovery move is not “try again.” It is “freeze the runaway run.” Stop adding instructions. Stop widening the file set. Decide whether the current attempt still contains a usable artifact or whether it should be treated as a failed branch of work.

The six failure families to identify before rerunning

Most large-repo failures land in one of six buckets.

1. Scope failure

The task mixed exploration, planning, editing, testing, and rollout into one request. The run never had a clean unit of work.

2. Context failure

The model saw too much repo noise, not enough local convention, or stale exploratory material that no longer matched the real slice of work.

3. Tool-path failure

Commands were run in the wrong environment, outputs were summarized in chat instead of saved to disk, or the repo hooks and tests were not actually reachable.

4. Handoff failure

The run sounded complete, but the next operator could not find the files changed, the logs produced, or the unresolved risks.

5. Verification failure

The system kept retrying without a sharp test, diff check, or contract check that could prove whether it was getting closer to correct.

6. Approval-timing failure

Routine edits and risky changes were mixed together, so the run stalled only when it reached review, permissions, or execution boundaries.

Those buckets matter because they give you a diagnosis order. If the task shape is wrong, a bigger context window will not fix it. If the tool path is broken, a stronger model will not fix it. If the artifact is missing, nobody downstream can recover the work quickly.

The diagnosis order that saves time

Use this order every time a large-repo run goes sideways:

1. re-scope the task
2. reload only the minimum context
3. verify the tool path
4. rebuild the handoff surface
5. add one meaningful verification gate
6. separate risky work from routine work

That order is boring on purpose. It forces the workflow to become legible again before you spend more intelligence on it.

A practical recovery playbook

Freeze the run

Do not keep the same long session alive just because it already consumed tokens. If the run has become noisy, treat that as sunk cost. Preserve any usable artifact, then stop the drift.

Re-scope to one bounded artifact

Pick one file boundary, one diff boundary, or one output path for the next pass. Name the non-goals explicitly. If the run is supposed to patch a failing serializer, it is not also supposed to redesign adjacent abstractions.

This is where many teams recover fastest. They stop asking the agent to “fix the subsystem” and start asking for a reviewable patch in one place.

Reload only the context that matters

Give the next pass the exact files, interfaces, failing test, local convention examples, and command path needed for that slice. Do not attach the whole repo tour. Context recovery is usually more valuable than context expansion.

Check the tool path before blaming the model

Make sure commands execute in the right worktree. Make sure outputs land in canonical paths. Make sure the build, lint, typecheck, or local test hook still works. If the system can only describe work in chat but cannot leave artifacts on disk, the run is not recovered.

Rebuild the handoff package

Require exact file paths, the command used, the observed result, and the unresolved risk. The next operator should not need to reread the whole transcript to continue. Missing artifacts are not a cosmetic issue. They are a workflow failure.

Add the smallest meaningful verification gate

Use one check that can fail clearly. That might be a failing test reproduction, a lint pass, a type check, a screenshot comparison, or one repo-specific contract check. The goal is not perfect coverage. The goal is to stop speculative retries.

Split risky work from reviewable work

If the run touches migrations, infra, permissions, or broad refactors, isolate those steps from the routine edits. Surface approvals earlier. Teams that want a clean pattern here should pair this with How to Design an AI Agent Approval System That People Actually Use and How to Split Work Between Cheap Models, Premium Models, and Humans Without Chaos.

When escalation is actually justified

Escalation is useful after workflow shape is clean, not before.

Move to a stronger model, specialist workflow, or human maintainer when all of the following are true:

• the task is now bounded
• the relevant context slice is clean
• the tool path works
• the handoff artifact exists
• the verification gate is clear
• the remaining blocker is actual reasoning depth, repo-specific judgment, or risk ownership

That is a much healthier escalation point than the common alternative, which is throwing a premium model at a badly formed task and hoping it compensates for missing operations discipline.

It also helps contain code churn. Teams that keep widening broken runs often get lots of motion but very little stable progress, which is exactly the kind of waste described in Tokenmaxxing for AI Coding Teams Creates Code Churn.

Recovery discipline is also cost discipline

Large-repo AI coding failures are not only reliability failures. They are budget failures.

Every extra retry, every lost handoff, and every review pass spent reconstructing what the agent actually did increases the real cost of the task. Teams that recover well do not just ship safer changes. They reduce rework, shorten review time, and avoid buying more model power than the workflow can productively use.

That is the real rule for large-repo recovery: fix the workflow shape before you buy more intelligence.

If a run cannot produce a bounded artifact, a clear verification path, and a clean handoff, it is not recovered yet, no matter how confident the chat transcript sounds.

AI Disclosure

This article was researched and drafted with AI assistance, then shaped into a practical working draft for editorial review.