Give a coding agent enough context to find a fix

Software that reads a repository to investigate a bug faces the same problem a new engineer faces on their first day: the code is unfamiliar, the symptom is described in someone else's words, and the connection between the two is not obvious.

A new engineer compensates by asking questions. Automated analysis cannot, so whatever context it gets at the start is the context it has. Assembling that context well is most of the difference between a useful result and a confident wrong answer.

Why is a vague symptom worse for automation?

A human reading "the checkout is broken" will ask which step, and will notice when their assumption stops matching the evidence. Automated analysis will pick an interpretation and pursue it.

If the interpretation is wrong, the search is thorough and misdirected. Worse, the output can be fluent and specific — naming a real file and a real function — while describing a defect that does not exist. Fluency is not accuracy, and a plausible wrong answer costs more than no answer, because someone has to disprove it.

The mitigation is not a cleverer reader. It is better input and stricter output rules.

What context is actually required?

Five things, and their absence degrades results in predictable ways.

The exact revision. Reading current code for a report against an older build produces conclusions about code that never ran. This is the single most common source of wasted analysis, and it is entirely preventable — see pinning the deployed commit.

The observable symptom. Not an interpretation. The page path, the action, the exact error text, the failed request with its method, path, status, and duration. These are searchable strings that map to real locations in the source.

The expectation. What should have happened. Without it, a reader cannot distinguish a defect from intended behaviour they simply do not like.

The boundary. Which repository, which branch, and the fact that only reading is permitted. Unbounded scope produces unbounded exploration.

The stopping condition. What to do when the evidence does not support a conclusion. Absent that instruction, the pressure is to produce something, which is exactly when invented causes appear.

Why must the access be read-only?

Because investigating and changing are different operations with very different risk.

Reading code to explain a symptom needs no authority to push a commit, alter a branch, create a release, or run repository scripts. Granting those capabilities to an investigation adds no diagnostic power and adds a category of damage that is hard to undo.

There is a second reason, about trust rather than risk. A read-only investigation produces a recommendation a human evaluates and applies. A system that both diagnoses and changes collapses those steps, and the review that would have caught a wrong diagnosis disappears with it.

Isolation matters for the same reason. An investigation confined to a copy of the repository at a specific revision cannot affect production data, other customers, or your account, regardless of what it concludes.

What makes a result trustworthy?

The result has to be checkable, which means three properties.

Citations to specific locations. A file and a line range at a known revision is a claim you can verify by opening the file. "The issue is in the profile handling" is not.

A separation between what is known and what is assumed. Evidence, conclusion, and unknown facts should be distinct sections. Collapsing them into a confident narrative hides exactly the parts that need scrutiny.

A calibrated conclusion. "Confirmed" should require more evidence than "possible". A conclusion that the source explains the symptom should require actual source evidence, and a stronger claim should additionally require direct evidence from the visitor's browser.

And the result must be allowed to say unknown. An investigation that hits its limits without a supported conclusion should say so plainly, with what it examined and what remains unclear. That is a useful outcome: it narrows the next attempt. A fabricated cause does the opposite.

What should a human still do?

Review before anything reaches a customer, always.

Check that the cited locations say what the result claims they say — this is fast, because a citation points at a specific place. Check that the conclusion strength matches the evidence. Check that the recommended action is proportionate. And check that any customer-facing text reveals nothing about your internal structure: a visitor should never receive a reply naming source paths or filenames.

Automated investigation is best understood as preparation, not decision. It gathers evidence, points at specific code, and drafts a response. The judgement remains yours.

How IssueProbe structures this

Each eligible report starts one isolated, bounded, read-only investigation against your repository at the revision recorded for that report. The investigation can clone the approved repository, read and search source, inspect the safe report evidence, inspect a visitor-approved screenshot, and register source citations. It cannot push a commit, run arbitrary repository scripts, change production data, alter a website account, release code, or send a response to anyone.

The result contains a short conclusion, a conclusion status, source-backed citations, important unknown facts, a recommended action, and a draft response. A likely or confirmed conclusion requires registered repository evidence, and a confirmed conclusion additionally requires direct visitor-browser evidence, so a hypothesis is not presented as a fact. Every citation is checked against an authoritative evidence manifest.

An investigation that reaches its bounded exploration limit still returns a readable result with an unknown cause rather than failing silently. A human reviews the result, edits the draft response without changing the immutable result, and decides what happens next. IssueProbe does not send the draft, and never emails visitors.

If you automate your own setup, the agent setup guide documents the owner-authorized API sequence, and the API reference covers the operations. See the example report for how a reviewed result keeps evidence, conclusion, and unknown facts separate.