How Much Context an Agent Needs to Fix a Finding
Quick answer: There is no fixed token count that makes context enough. The agent needs enough to see the trigger, the connected code that decides it, and the expected behavior, and how much that is depends on the blast radius. A leaf-function defect needs the block and the helper, while a shared-module defect needs every caller. Give too little and the agent fixes the wrong thing, give too much and it gets distracted or changes unrelated code.
Why file count is the wrong measure
Reviewers often ask whether to include five or ten files, which treats context as a quota. The real measure is whether the agent can answer three questions without guessing: what fires the defect, what code the trigger runs through, and what the correct result should be. The number of files that takes varies with the finding.
A change in a leaf function is explainable with a tight block, while a change in a shared helper reaches many callers, and the same number of files would be too much for the first and too little for the second.
Context by finding type
| Finding type | Context that is needed | What extra context adds |
|---|---|---|
| Leaf function | The block and the helper | Little beyond the immediate code |
| Shared helper | The block plus every caller | The operations the change reaches |
| Data shape or type | The producers and consumers | Every step that reads the field |
| Multi-step flow | The chain and the handoffs | The extracted values between steps |
| Guard or validation | The branch and the reaching data | The values that can and cannot pass |
The right-hand column is the clue. When extra context changes the blast radius, it is needed, and when it only adds unrelated files, it is not.
Sizing the context
- State the trigger and the expected behavior so the target is clear.
- Include the enclosing block and the symbols the line uses.
- If the code is shared, add every caller until the blast radius is fully shown.
- If a data shape changes, add the producers and consumers of that field.
- If the defect sits in a flow, add the chain and the extracted values.
- Stop when the three questions are answerable, and cut anything beyond that.
Take a shared filter helper. A tight block would show the helper but not the two callers, and the agent might add a guard that breaks the caller that passes the full list. Including both callers shows the different inputs, and the agent fixes only the path that reaches archived notes. For a leaf function with no incoming references beyond one caller, the same amount of context would be wasted, and the block plus the single caller is enough.
Too little and too much
The two failures are different. Too little context produces a confident fix aimed at the wrong trigger, because the agent cannot see the caller or the data that decides it. Too much context produces scope creep, where the agent starts editing unrelated files that were included without a clear link.
The bounded-context design keeps the review focused on connected code, and the task package pins revision anchors so the agent works from the exact state the reviewer read.
Powerduck sizes the exported context to the connected code and the blast radius, rather than exporting a fixed file count.
Re-sizing after the first fix
The context size is not fixed for the life of a finding. If the first fix changes a shared helper, the blast radius can widen and new callers enter the picture, so the context has to grow to match rather than staying at the original block. Conversely, once a guard narrows the trigger, some earlier context may no longer be reachable and can be set aside. Re-check the size after each revision by asking the same three questions again, and adjust the package to the new blast radius. A package that fit the first attempt may be too thin for the second, and shipping a fix against stale context is how a small change reaches code the reviewer never re-examined.
Honest limits
Static context can miss dynamic loading and external consumers, and a branch that looks unreachable locally may be live at runtime, so the context may need a real request to expose the real trigger. The review can raise false suspicions or miss defects, and an AI-only claim stays a hypothesis.
When the fix lands, verify it with the same request that exposed the defect rather than trusting the agent's report.
Frequently asked questions
Is there a recommended number of files? No. Size the context by whether the trigger, the connected code, and the expected behavior are clear, which depends on the blast radius.
What happens with too little context? The agent fixes the wrong trigger because it cannot see the caller or the reaching data.
What happens with too much? The agent edits unrelated code and the change loses its focus.
The bottom line
Do not measure context in files or tokens. Give the agent the trigger, the connected code, and the expected behavior, and expand to every caller or producer when the change is shared, stopping once those three questions are answerable. Too little causes a wrong fix, too much causes scope creep, and the blast radius is what sets the right size. Confirm the result with a real request, and keep AI-only claims as hypotheses. Read more in the AI code review guide.