Docs / Guides

Updated July 25, 2026 · About a 9 minute read

Auto-Fixing Lint Errors, Broken Tests, and Missing Dependencies

Most build failures are not bugs. They are the same three mechanical problems that keep recurring: a formatting flaw, a test broken because you changed what it checked, a package you forgot to install. Here is how to make them fix themselves - safely - so your attention goes to the failures that actually matter.

The failures that keep coming back

Look at a week of red builds and a pattern emerges. A large share of them are not flaws at all. They are drift, bookkeeping, and forgetfulness: a file that never went through the formatter, a snapshot that no longer matches after an intended text change, an import pointing at a dependency you never added to the manifest.

These failures share three traits that make them special:

• They are mechanical - the fix is a known transformation, not a judgment call.
• They are verifiable - rerunning the check tells you immediately whether the fix worked.
• They recur - the same failure category shows up again next week, and the week after.

Anything mechanical, verifiable, and recurring is a candidate for automation. That is the whole thesis of this guide: identify that set, automate it behind a review step, and stop spending human attention on it.

The three categories that are safe to auto-fix

Not every failure belongs to the automatable set. Three categories do, and it is worth being precise about what qualifies.

1. Lint and formatting. This is the safest category by a wide margin. A linter or formatter has a deterministic notion of correct: whitespace, quote style, unused imports, trailing commas, import order. The tool itself usually provides an autofix. There is no ambiguity about intent, so applying the fix and rerunning is nearly risk-free.

2. A test broken by a known change. This is the delicate category. If you renamed a function and three tests now reference the old name, the fix is mechanical - update the references. If you deliberately changed a heading from "Sign in" to "Log in" and a snapshot test fails, the fix is to update the snapshot. The key criterion is a known change: the test broke as a direct and expected result of something you meant to do. A test that broke for a reason you cannot explain does not belong in this category - it may have caught a real bug.

3. A missing dependency. An import that resolves to nothing, or a fresh checkout that fails because a package is used but never declared. The fix is to install it and add it to the manifest at a reasonable version. This is bookkeeping, and it is verifiable: once it is declared and installed, the resolution error disappears.

Why an agent should propose a diff, not commit blindly

The instinct with automation is to close the loop entirely: detect the failure, fix it, commit, move on. Resist that instinct. The correct output of an automatic fix is a proposed diff for your approval, not a commit that already happened.

The reason is the failure mode of the middle category. An agent asked to make a failing test pass has two ways to succeed: fix the code, or gut the test. Deleting an assertion, loosening a matcher, or wrapping the whole thing in a skip all turn the build green while destroying the very signal the test was there to give you. If that lands quietly, you did not fix a failure - you hid a bug in your history.

A diff you can read in a few seconds closes that gap. You see that the snapshot update is exactly the text change you made, that the added dependency is the one you actually import, that the lint fix touched only whitespace. Approve, and it lands. Something looks off, and you catch it long before it reaches main. The diff is the trust boundary.

The diff-review loop

Put the pieces together and you get a tight loop that runs on every failure:

1. Detect and classify. A check fails. Is it lint, a test broken by a known change, a missing dependency - or something outside the safe set?
2. Generate a candidate fix. For the safe categories, produce the minimal change that addresses the failure and nothing beyond it.
3. Rerun to verify. Apply the fix in a temporary state and run the check again. If it is still red, the fix was wrong; do not surface it.
4. Propose the diff. Show a verified-green diff for approval, with a one-line explanation of why it failed and what the fix does.
5. Approve and land. You read, approve, and it lands as a commit. Reject, and it is discarded with the reason logged.

Run this consistently and the numbers add up fast. In practice, a loop like this resolves roughly 70 percent of recurring failures - the mechanical ones that used to interrupt you daily - with no manual work beyond a glance at the diff. The remaining 30 percent are the real bugs and design questions, and now you meet them with a clear head instead of a queue of formatting flaws ahead of them.

Guardrails: when not to auto-fix

The loop is safe only because it knows its limits. These are the cases where an agent should stop and hand everything back to you, with no fix applied:

• A test fails for an unexplained reason. If the agent cannot tie the failure to a specific known change, assume it caught a real bug. Report, do not fix.
• The fix would weaken a test. Deleting assertions, loosening matchers, adding skips, or narrowing coverage to reach green is never an automatic fix. It is the anti-pattern the whole approach exists to prevent.
• A dependency change carries risk. Adding a small missing package is bookkeeping; a major version bump, a package with native builds, or anything touching a security surface needs a human decision.
• The blast radius is large. A "fix" that rewrites dozens of files to satisfy a single failure is a design change in disguise. Escalate it.
• The same fix keeps failing verification. If two or three attempts still leave the check red, the problem is not mechanical. Stop guessing and surface it.

A good rule: only automate what you would confidently approve in five seconds. The moment a fix requires real thought, that thought is yours to give.

Building trust in the automation

You do not have to hand over the whole loop on day one. Trust is earned in stages, and the safe categories have a natural order:

• Start with lint and formatting. The risk is near zero and the volume is high, so you feel the benefit immediately while watching the agent behave.
• Add missing dependencies next. Still mechanical, slightly higher risk, easy to verify from the diff.
• Bring in known-change test fixes last. This is where judgment matters most, so it benefits most from the diff-approval habit you have already built.

Keep a log of every proposed and approved fix. After a few weeks you will see which categories you approve without hesitation and which you routinely reject - and you can tune the loop to stop proposing the ones you always reject. Automation that learns from your rejections is automation you will keep using.

Frequently asked questions

Which build failures are safe to fix automatically?

The safe categories are mechanical and verifiable: lint and formatting violations, a test broken as a direct result of a change you meant to make, and a missing dependency that needs to be installed or declared. Each has a correct answer you can check, so a proposed fix together with a rerun confirms it. Failures that hide a real bug, a design decision, or unclear intent are not safe to auto-fix.

Should an AI agent commit fixes automatically or ask first?

It should propose a diff for approval instead of committing blindly. A diff you can read in seconds keeps you in control, catches the case where the agent "fixed" a test by deleting its assertion, and builds trust over time. Blind commits just move the failure from the build log into your git history, which is worse.

How many of my recurring failures can this actually clear?

In practice a diff-review loop resolves roughly 70 percent of recurring failures - the mechanical ones that keep coming back: formatting drift, a snapshot that needs updating after an intended change, a package that was not installed. The remaining 30 percent are real bugs and design questions that deserve your full attention, which is exactly where the saved time goes.

Go deeper: Autonomous coding agents, explained - what an agent can safely do on its own, and where the human stays in the loop.