An AI coding agent can investigate a repository faster than most engineers can open the relevant tabs. It can find call sites, trace configuration, compare tests, read commit history, and return a surprisingly coherent account of what it thinks is happening.

That is useful reconnaissance. It is not yet an engineering plan.

The gap matters because investigation answers questions such as "where is this behavior implemented?" A plan must answer a harder set: "what should change, why is that the right boundary, what must remain true, how will we know it worked, and who owns the decisions the evidence cannot make?" An agent can gather and organize the inputs. A responsible engineer still has to turn those inputs into an accountable proposal.

The good news is that this does not require a heavyweight design document for every bug fix. It requires a compact handoff contract that separates what the agent observed from what it inferred, then makes the remaining decisions visible before code starts moving.

Treat investigation notes as evidence, not a conclusion

Agent output often arrives in a form that sounds more final than it is:

The cache bug is caused by SessionLoader writing an empty result, so update the loader and add a regression test.

That sentence may be correct. It may also mix together an observation, a causal claim, a proposed implementation, and a test strategy. Those are different things with different confidence levels.

Start by translating the notes into four buckets:

This simple separation prevents a common failure mode: fluent prose quietly promotes an inference into a requirement. Agents are especially good at making local code look like a complete explanation. Production systems have contracts outside the local codebase—operational behavior, compatibility expectations, customer workflows, ownership boundaries, and history—that may not be visible in the files the agent read.

Ask the agent to cite each important claim with a path, symbol, test name, log excerpt, issue reference, or command output. If it cannot point to evidence, label the statement as an assumption. That does not make the observation useless. It puts it in the right place in the plan.

Restate the problem in behavior, not file names

Once the evidence is organized, write a short problem statement that a reviewer can validate without knowing the investigation transcript. It should describe the observable failure and the desired behavior.

Weak:

Change SessionLoader, CacheAdapter, and the auth test.

Better:

When an authenticated request has no resolved user, the service should not persist an empty user cache entry. Existing cache behavior for resolved users and explicitly supported negative-cache callers must remain unchanged.

The better statement defines an outcome and an invariant. It does not pretend that the current files are necessarily the final implementation boundary. That is important when an agent's first pass finds several similar paths. The plan can say which one is in scope and why, while preserving the option to stop if the evidence points somewhere else.

This is the same discipline that makes an agent prompt useful. How To Write Agent Prompts That Produce Reviewable Pull Requests frames a prompt as a change contract. A plan is the next artifact in that contract: it says what the investigation found and what the accountable human has decided to do with it.

Define the smallest credible implementation slice

The plan should name the files or components likely to change, but it should also state why each belongs in the slice. This turns a list of files into a review boundary.

For a small behavior correction, that might look like this:

1. Update SessionLoader so it distinguishes an unresolved user from a cacheable resolved user before calling the cache adapter.
2. Add a focused regression test at the loader boundary proving that an absent user does not create a cache write.
3. Retain the existing successful-user cache test as the guard against changing normal behavior.
4. Do not change cache TTL policy, cache key format, or unrelated authentication flows in this patch.

The exclusions are not filler. They protect the change from the agent's natural tendency to clean up related-looking code while it has the repository open. A good plan names the tempting adjacent work and deliberately leaves it for a separate decision.

How To Keep AI Coding Agent Changes Small Enough To Review goes deeper on why a bounded diff is a quality control, not a cosmetic preference. A plan is where that boundary is set before a large diff exists.

Make the decisions and tradeoffs explicit

The highest-value part of the plan is usually not the implementation steps. It is the two or three decisions that could reasonably go another way.

For each one, write the choice, the evidence, the tradeoff, and the owner:

This table is intentionally ordinary. It is a defense against plans that hide the actual product or operational decision behind technical wording. The agent may surface the options, but it should not silently choose a compatibility or cost tradeoff just because one implementation is shorter.

If the decision is genuinely unresolved, do not paper over it. Put a stop condition in the plan: "Do not implement until we confirm whether negative caching is an intentional protection against abuse." That is progress. A clear unknown is cheaper than an elegant wrong patch.

Design validation before the implementation

"Run the tests" is not a validation plan. It is a reminder to run the normal machinery. A credible plan specifies which evidence will demonstrate the risk was addressed and which existing contract must remain intact.

Use layers that match the change:

• Targeted regression test: Reproduces the failing behavior and proves the intended behavior after the change.
• Neighboring contract test: Keeps the closest successful or compatibility path from changing accidentally.
• Repository checks: Run the formatter, type checker, unit suite, or build command that normally guards the affected code.
• Operational verification: For a production-sensitive path, name the log, metric, dashboard, or rollback signal that will be watched after release.

When an agent reports that a test passes, keep the command and the result in the plan or pull request. When it reports that a test cannot run, record the reason and the remaining risk. Evidence that is inconvenient to collect does not become optional because the agent's summary is confident.

Use a reusable plan template

For most repository changes, this compact template is enough:

Problem
- Observed behavior:
- Desired behavior:
- Invariants:

Evidence
- Paths, symbols, tests, logs, and commands that support the plan:

Decisions and open questions
- Decision, rationale, tradeoff, owner:
- Open question and stop condition:

Implementation slice
1. Change:
2. Test:
3. Explicit exclusions:

Validation and rollout
- Targeted checks:
- Broader checks:
- Post-release signal and rollback condition:

The template is deliberately short. A two-file bug fix does not need a ten-page plan. A multi-service behavior change may need a diagram, rollout stages, and a review from the owning team. The standard is proportionality: enough structure that a reviewer can challenge the reasoning, but not so much ceremony that the team stops writing plans for ordinary work.

The handoff is the product

The best outcome from an agent investigation is not a longer transcript. It is a handoff that lets a human make a better decision quickly: the evidence is traceable, the proposed scope is bounded, the assumptions are visible, and the validation is known before the patch begins.

That is how AI-assisted investigation becomes an engineering multiplier instead of a source of plausible-looking churn. Use agents to map the terrain. Use an engineering plan to decide where to build, what not to disturb, and how you will know the work holds up.

For more practical engineering essays and tools, visit Slaptijack.