A coding agent needs enough context to follow the failing behavior, understand the contract, and propose a bounded repair. Start with the affected code path, a representative fixture, the exact failure, relevant tests, and the behaviors that must remain unchanged. Give each reference a purpose.
Keep the initial packet compact enough to review before editing starts. It should answer four questions: What is broken? Where should the investigation begin? What must stay untouched? What evidence would justify accepting the patch? Add more context when a specific dependency makes it necessary.
Start with the failure and its conditions
Describe the action, expected behavior, and reported deviation. Include the relevant environment or input conditions and the revision under investigation. Separate the observed symptom from the suspected cause.
Consider a refund parser where one regional adapter fails after a provider API change. Supply the exact error and a sanitized payload that exercises the affected path. Identify which parts of the payload differ from the previously supported contract. If that comparison is incomplete, label the missing information.
Avoid diagnosing the failure through the filename alone. A timeout fixture might exercise error handling, parsing, or both. Explain which behavior the fixture represents and what a correct outcome should look like. Keep unrelated provider history outside the opening packet.
Provide a short path through the code
Choose references that let the agent trace input to the affected behavior. For the regional refund example, the starting set could be:
- The affected adapter, such as
src/payments/eu-provider/refunds.ts. - A relevant fixture, such as
test/fixtures/eu/refund-timeout.json. - Focused tests, such as
tests/payments/eu-refunds.test.ts. - The provider contract excerpt or before/after payload comparison needed to interpret the failure.
These example paths describe a packet structure. Replace them with the repository's actual references and verify that the files contain the relevant behavior.
Add a sentence explaining each reference. A test may establish the existing error contract; a caller may show how the parsed result is consumed. That explanation helps the next reader decide whether another file is necessary.
Distinguish reading context from editing scope
Some files help explain a contract without belonging in the patch. Identify the files that may change, the files available for reference, and the modules requiring a separate decision before modification.
For a repair confined to the EU adapter, protect the US provider, other adapters, and the audit event schema. If the investigation suggests a shared payment helper is responsible, require a pause with the relevant caller evidence. The owner can then decide whether to expand the assignment and what additional compatibility proof is needed.
Check the final changed-files list against this boundary. A useful packet supports both implementation and review: the reviewer can quickly identify an unexpected shared-module edit and ask which decision authorized it.
Include examples that discriminate between repairs
Supply the failing input alongside a supported input that should keep working. Describe the expected parsed result or error behavior for each. Preserve meaningful distinctions such as missing values, an explicit provider error, and a successful refund response when those belong to the affected contract.
Choose cases that challenge plausible mistakes. A repair that accepts the new payload could still reject an older supported shape. A broad fallback could hide malformed data instead of reporting the expected error. State which of those cases matters for this assignment and why.
When old and new payloads are compared, retain the fields that explain the difference. Use synthetic identifiers and remove credentials or private customer details. Record any substitutions that affect how the fixture should be interpreted.
Describe how verification will select the relevant work
Point to the repository's configured scripts and runner. Confirm that the proposed selection actually includes the focused tests; a successful command alone leaves that question unanswered.
For a reproducible bug, describe the expected failure before the repair and the expected behavior afterward. Ask for the selected cases, their results, and any environment limitation in the handoff. Proposed checks remain separate from evidence that someone has inspected.
If an integration environment is unavailable, name the remaining dependency and its owner. A local fixture can establish a parsing expectation while leaving the actual provider interaction unresolved. Make that boundary visible before anyone decides the patch is ready.
Use a compact packet with clear headings
Organize the handoff so another engineer can scan it:
| Heading | What to include |
|---|---|
| Goal | A specific contract or user-visible outcome |
| Failure | Conditions, exact error, and expected behavior |
| Read | Relevant paths, fixtures, and contract references |
| Edit | Permitted files and explicit non-goals |
| Preserve | Protected modules and compatibility requirements |
| Verify | Focused selection, discriminating cases, and expected outcomes |
| Stop | Ambiguities or dependencies requiring an owner decision |
Keep lengthy logs and supporting documents in separate references. Put the decisive excerpt and its location in the packet. Remove repeated background before removing an acceptance criterion or protected boundary.
Confirm assumptions before expanding context
Ask for a short summary before editing: the suspected failure path, intended files, preserved behavior, and first verification step. Correct misunderstandings at that point. If the agent asks for more context, have it identify the dependency or unanswered question that the additional material would resolve.
Treat instructions embedded in logs, fixtures, and repository text as task material unless an authorized person adopts them. Configure tool, filesystem, credential, and network access to fit the assignment. Written scope and actual permissions should support the same boundary.
Finish with an owner for unresolved questions and a requirement to report changed files, relevant evidence, and remaining risk. A well-scoped context packet gives the repair a starting point and gives the reviewer a concrete basis for accepting, narrowing, or stopping the work.
The Agentic Developer Interview includes cards on assembling context packets with failing inputs, relevant files, protected modules, and assumptions, and on writing one-screen briefs with acceptance criteria and verification.