Quick answer: A review context package should carry enough connected code to make the confirmed finding self-contained, and no more. Include the suspicion and its anchor, the enclosing block with resolved symbols, the callers and the reaching data, the evidence that confirmed it, and the revision anchors. Dumping the whole codebase adds noise and can mislead the agent, while a package that is too thin forces it to rediscover the context you already worked through.
Why the package needs a boundary
The purpose of the package is to transfer the exact context the reviewer used to confirm the defect. Code that is connected to the suspicion, the block, the helpers, the callers, belongs in it, and code that is unrelated does not, because unrelated files dilute the focus and can pull the agent toward changes nobody asked for.
There is a real trade-off. A thin package is focused but can leave the agent missing a caller that decides the trigger, and a heavy package is complete but slow to read and full of distractions. The boundary is the connection to the confirmed finding.
The contents, ranked by necessity
| Content | Why it belongs |
|---|---|
| Confirmed suspicion and anchor | The defect and where it sits |
| Enclosing block | The branch or loop that contains the trigger |
| Resolved symbols | What the variables and helpers actually are |
| Reaching data | The values that can arrive at the line |
| Callers | The operations that reach the code |
| Evidence and raw output | The request that reproduced the defect |
| Revision anchors | The code state the review is based on |
| Expected behavior | What the correct result should look like |
The first five items make the trigger understandable, and the last three make the fix checkable.
How to assemble it
- Start from the confirmed suspicion and the code anchor, not from the repository root.
- Add the enclosing block and resolve every symbol the line depends on.
- Trace the reaching data and the callers, stopping when the trigger is fully explained.
- Attach the request and the raw output that confirmed the defect.
- Pin the revision anchors and state the expected behavior after the fix.
- Cut any file that is not connected to the finding rather than including it for completeness.
Take a deletion-filter defect. The package holds the flagged line, the handler block, the resolved filter helper, the two callers, and the data showing one passes archived rows. It includes the request that removed the archived note and the expected behavior that the note should survive. It does not include the unrelated preferences module or the renamed imports elsewhere, because none of them connect to the trigger. The agent can understand and fix the defect from the package alone.
How to judge whether it is enough
A simple test is whether a reviewer can explain the trigger and the expected fix without opening another file. If a question remains about which caller reaches the line or what values can arrive, the package is too thin and needs that context. If a file sits in the package without a clear link to the finding, it is noise and should come out.
The review reads differences with bounded related context, which keeps the package focused on connected code, and the parser resolves the symbols locally rather than relying on names.
Powerduck exports the connected context and the revision anchors together, so the handoff stays self-contained without becoming a code dump.
Ordering the package for readability
Put the finding and the anchor first, then the block and the symbols, and leave the callers and the evidence after the trigger is clear. A reviewer reading the package should meet the defect before the supporting detail, so the context explains a claim they already understand rather than arriving before the point. Keep the revision anchors at the end, and label the expected behavior clearly so the fix has a checkable target.
Honest limits
Static context can miss dynamic loading and framework entry points, and an external consumer may reach the code in a way the local caller list does not show. No incoming reference does not make a file safe to delete, and the review can still miss defects.
When the reaching data cannot be captured from the static code, include a real request that observes it rather than guessing, and keep an AI-only claim as a hypothesis.
Frequently asked questions
How much code should the package include? Everything connected to the confirmed finding, from the block and symbols to the callers and data, and nothing unrelated.
What is the risk of a too-thin package? The agent misses a caller or the reaching data and has to rediscover the context or fix the wrong thing.
How do I know the package is complete? A reviewer can explain the trigger and the expected fix without opening another file.
The bottom line
Build the context package around the confirmed finding, including the block, resolved symbols, reaching data, callers, evidence, and revision anchors, and cut any file that is not connected. A self-contained package lets the agent fix the defect without rediscovering it, while a code dump just adds noise. Judge completeness by whether the trigger and the expected fix are explainable from the package alone, and use a real request when the static view cannot capture the data. Read more in the AI code review guide.
Top comments (0)