Give a Coding Agent Enough Debugging Context Without Dumping Everything

Give a debugging agent enough material to distinguish the next plausible explanations: the failing input, the expected behavior and its source, the relevant environment, and the code or log that connects the input to the failure. Choose additional material by the question it answers. There is no fixed ideal packet size, and shorter context is not automatically better.

GitHub's task guidance recommends clear scope, acceptance criteria, and directions to relevant files. Anthropic's context-engineering article describes selecting useful information within a limited context window, while noting that minimal context need not be short. The selection exercise below applies those ideas to one fictional parsing problem.

Define the boundary before selecting attachments

Imagine a report exporter followed by an importer. One exported file fails to import when a label contains a semicolon. The investigation question is: “Does the importer preserve a semicolon inside a quoted field?” That question determines which bytes, settings, and source excerpts matter.

All names, inputs, code, requirements, and records below are original fictional teaching material. No customer file is reproduced, no agent diagnostic result was measured, and none of the example code was executed.

The fictional format note, EX-7, says:

Columns: id;label
Delimiter: semicolon (U+003B).
Fields may be enclosed in double quotes (U+0022).
A semicolon inside a quoted field belongs to that field.
This investigation covers one data row and no embedded line breaks.

The failing fixture, fixtures/quoted-label.txt, is exactly:

id;label
x;"North; West"

It represents one data row whose label is North; West. A nearby comparison fixture replaces that row with x;North West, which has no embedded delimiter. The comparison changes one relevant feature without introducing real customer data.

The relevant excerpt from src/read-export.js is:

// Excerpt: header parsing and later row construction are omitted.
const expectedFields = headers.length;
const fields = line.split(";");
if (fields.length !== expectedFields) {
  throw new Error(
    `row=${rowNumber}; expected=${expectedFields}; actual=${fields.length}`
  );
}

An invented incident note records the message row=2; expected=2; actual=3. That message is part of the exercise, not captured terminal output. Manual inspection suggests the delimiter split is a useful place to investigate, but the surrounding parser and call path still need inspection before choosing a repair.

Compare three possible material packets

Packet A: too little to choose a next check

Import is broken. It says the columns are wrong. Please fix the parser.

This omits the input, format rule, exact message, and code path. The agent cannot tell whether the row is malformed, the delimiter setting is wrong, or the implementation handles quoting incorrectly. It also cannot tell what “fixed” means.

The missing material is specific. Add the two-line fixture, EX-7, the exact error note, and the relevant parser excerpt before adding an entire repository archive.

Packet B: enough to investigate this boundary

Problem: importing quoted-label.txt is reported to reject data row 2.
Expected: one record with id x and label North; West, following EX-7.

Input: the exact two-line fixture quoted-label.txt supplied above.
Comparison: the same header with the row x;North West.
Format rule: semicolon delimiter; semicolons inside double-quoted fields
belong to the field. No embedded line breaks in this investigation.

Code: src/read-export.js, row field-splitting and field-count excerpt.
Caller: src/import-report.js calls readExport with the selected input text;
the full caller and parser are available for read-only inspection.

Environment note: fictional Table Importer revision EXAMPLE-P6;
UTF-8 fixture, LF line endings, semicolon format selected.
The JS runtime version was not recorded and must be checked if relevant.

Incident note: row=2; expected=2; actual=3.
Execution status: supplied as a fictional record; no command run here.
Request: investigate first; explain the smallest evidence-backed repair.

This packet contains the evidence needed to ask a focused question and admits the missing runtime information. The full caller is a named next source, not an attachment the agent is assumed to have read.

Packet C: more material without a clearer question

Everything in Packet B, plus:
- the full production export with thousands of unrelated rows;
- the account's complete environment configuration;
- all application logs for the past month;
- screenshots of the dashboard and unrelated rendering failures;
- an old conversation about a possible future file format;
- a list of all database tables and all dependency files.

For the current question, none of those additions has a stated diagnostic purpose. They can also introduce personal information, credentials, and obsolete assumptions. Keep them out of the initial packet. If the focused investigation reveals an encoding, configuration, or dependency question, retrieve the narrow relevant evidence then.

Make each inclusion earn its place

Material	Decision for this packet	Reason
Exact two-line failing input	Include	Preserves delimiter, quotes, spaces, header, and row boundaries
Fictional format note `EX-7`	Include	Establishes that the quoted semicolon is valid input
Exact error note	Include, labeled as reported	Connects the failure to the field-count check without inventing a stack trace
Field-splitting source excerpt	Include	Shows the transformation most directly related to that count
Caller path	Include as a source pointer	Lets the agent verify how text and settings reach the parser
Nearby input without a semicolon in the field	Include	Gives a comparison that changes one relevant input property
Encoding and line endings	Include	Defines the fixture's representation; no guess about a customer file
Runtime version	Mark unknown	Avoids inventing an environment; obtain it if behavior depends on it
Full production export	Exclude initially	Additional rows are unnecessary for the selected boundary
Complete environment configuration	Exclude	The task calls for selected settings, not credentials or every variable
Month of application logs	Exclude initially	No link from those unrelated events to the selected row
Dashboard screenshot	Exclude	Visual layout does not explain the shown parser transformation
Old future-format discussion	Exclude	It is not the current requirement; mixing it in could change the expected behavior
Dependency files	Retrieve only if needed	Relevant if proposing a parser dependency or checking an existing one, not yet a reason to expand the packet

The decision can change. If the minimized fixture stops exhibiting the reported problem in an authorized reproduction, do not insist that it is sufficient. Compare it with the original at the next relevant boundary: encoding, quoting, line endings, invocation, or configuration. Preserve original evidence in its approved location and share only what the investigation needs.

Copy this investigation request

Investigate one quoted-delimiter import problem before editing code.

Requirement EX-7:
The file has id;label columns separated by semicolons. Double-quoted
fields may contain semicolons. This case contains one data row and no
embedded line breaks.

Exact input:
id;label
x;"North; West"

Expected parsed record:
{"id":"x","label":"North; West"}

Comparison input:
id;label
x;North West

Reported error note:
row=2; expected=2; actual=3
This is an illustrative supplied record, not a new execution result.

Known source excerpt in src/read-export.js:
const expectedFields = headers.length;
const fields = line.split(";");
The following branch throws when the counts differ.

Read next:
The full src/read-export.js and its caller src/import-report.js.
Verify header handling, quote handling, actual input transformation,
and effective delimiter selection. Report missing files explicitly.

Known environment:
Revision label EXAMPLE-P6; UTF-8 fixture; LF; semicolon format selected.
Runtime version and a real reproduction result are not supplied.

Scope:
Read-only investigation. Do not install packages, execute application
code, access production exports, rewrite the format, or modify files.

Return:
Evidence-backed explanation with file/symbol references; the smallest
additional check if needed; and a bounded repair proposal preserving
EX-7. Separate observations in supplied material from predictions.
For any extra artifact requested, state the question it will answer.

Expand at the boundary that remains uncertain

If the agent finds that the full parser already handles quotes and the excerpt belongs to an unused path, the right next material is the actual call path. If the parser receives transformed text, inspect that transformation. If the proposal adds or changes a library, bring in its current documentation and the relevant dependency files at that point.

Useful context is the material that supports the next decision. In this example, the fixture, rule, transformation, and count belong together. The rest stays available through precise references until a question requires it.

For the CueSpec routing step, see check the intended conversation. Include critical evidence in the task or an accessible referenced file, and ask the agent to identify what it actually read.