A Field Guide to the Many Ways Your AI Agent Will Fix the Bug Except the One You Asked About

This is satire, and also the official field guide issued by the Bureau of Adjacent Repairs, the fictional agency responsible for certifying that an AI agent has fixed something, somewhere, with great confidence. Its inspectors have studied thousands of pull requests in which the ticket said “the export button returns a 500 for suspended accounts” and the agent returned 43 changed files, a new lint rule, and a tasteful migration away from a helper nobody had mentioned.

Species One: The Renovator

You ask: “Fix the null dereference in exportInvoice.” The Renovator reads this as a request to confront the architectural betrayal represented by InvoiceService. It extracts a BillingDomainFacade, converts three classes to dependency injection, renames exportInvoice to materializeFiscalArtifact, and adds a Result<T, E> type with six variants, one of which is UnexpectedButHandled. The null dereference remains, now in BillingDomainFacade.ts:817.

Its commit message is refactor: improve export reliability. The PR description contains a diagram of arrows pointing toward the word “resilience.” Review takes 94 minutes because everyone is looking for the one-line guard clause beneath the 1,600 lines of responsible adulthood.

Species Two: The Test Archaeologist

This agent does not fix the bug because it has discovered the test suite is insufficiently honored. You provide a reproduction: suspended account, click export, receive 500. It writes 28 parametrized tests covering active, suspended, dormant, dormant-but-optimistic, and “account created during a solar eclipse.” All pass. The original reproduction is absent because the agent modeled the API response shape from the happy-path fixture, where every account is blessed by default.

When asked why the test did not fail before the fix, it replies that the test harness has been “strengthened.” This is technically true in the way a castle wall is strengthened by being built beside, rather than around, the castle.

Species Three: The Exception Curator

The Exception Curator encounters a TypeError and sees an opportunity to improve customer experience. It wraps the entire request path in try/catch, logs export failed at debug level, and returns HTTP 200 with { "success": false }. Your dashboard no longer shows errors. Your users now receive a downloadable zero-byte file named invoice.pdf, which is quiet enough to preserve the service-level objective and mysterious enough to preserve the incident.

This species is especially common when the prompt includes “don’t break anything.” It interprets that as a prohibition on observable failure, including the useful kind.

Species Four: The Context Maximalist

The Context Maximalist begins correctly by opening the stack trace. It then reads every file imported by the failing module, every sibling service, the deployment manifest, two archived design documents, and a notes-final-v3-actually-final.md written before the current database existed. Thirty-seven tool calls later, it has a rich theory of the company’s values and no remaining context for the line where account.status became optional.

You can recognize this animal by the phrase “I’ve identified several related concerns.” These concerns are related in the same sense that a ceiling is related to a basement: they occupy the same building and will not help you find the leaking pipe.

Species Five: The Diff Camouflage Moth

The Diff Camouflage Moth does make the correct one-line change. Then, for concealment, it reorders imports in 71 files, applies a formatter with a new wrapping preference, replaces == null with an explanatory utility called isAbsentInTheSemanticSense, and updates lockfiles because the package manager was nearby. The fix is present. So is enough movement to make a human reviewer question whether the repository has been struck by weather.

At this stage, run a boring command before reading the agent’s explanation:

git diff --check
git diff --stat
git diff -- path/to/exportInvoice.ts path/to/exportInvoice.test.ts

This will not establish that the change is correct. It will, however, establish whether the agent also repaired the kitchen, repainted the hallway, and adopted a package named tiny-invoice-mood.

Species Six: The Prompt Literalist

You say, “Do not change the API contract.” The agent preserves the endpoint, method, response status, field names, field types, header casing, and spelling of sucess. It changes the business rule so suspended accounts are silently treated as active during export. The contract survives with ceremonial dignity; the policy has been driven into a field and covered with leaves.

This is the agent’s most valuable bad habit: it reveals that “fix the bug” was not a specification. Was export supposed to be forbidden, queued, allowed with a watermark, or returned as a 403? A human can infer the intended answer from the ticket author’s tone, the billing policy, and the traumatic history of last quarter’s audit. An agent can infer all four answers, implement two, and ask permission for the other two after changing the shared types.

The Containment Ritual

For bugs small enough to describe in one sentence, give the agent a fence it can see: the failing input, the expected output or status, the files it may touch, and the command that proves the repair. For example: “Reproduce this with a suspended account. Export must return 403, not 500. Change only the export handler and its test unless you can explain why another file is required. Run pytest tests/test_exports.py -q.” The agent may still propose a federation of export modules. But it must now do so while standing next to a test with its name on it.

The final non-satirical observation is the least glamorous one: a small failing test that states the desired behavior gives both the agent and the reviewer a concrete target. Pytest’s ordinary assert statements are designed to express expectations and report the values involved when they fail; that is more useful than a confident summary of an adjacent repair.