Start with an observable mismatch: what someone did, what should have happened, and what happened instead. Give the person fixing it enough information to repeat that mismatch and recognize it without sharing your preferred explanation.
“Search is broken” leaves too much room for guesswork. A useful report identifies the query, record, user, timing, and expected result. It also states which parts of the report remain unconfirmed. That gives a coding agent a bounded investigation and gives the reviewer a way to judge the eventual patch.
Separate the observation from the diagnosis
Imagine a customer record created at 10:03. An administrator can open its direct URL, but searching for part of its name produces no result until 10:11. The interface shows no error.
Those observations support several questions. Did indexing finish late? Did search apply different permissions? Was the result on another page? Did the query use stale data? Direct visibility alone does not choose among them.
Write the hypotheses below the observations. Keep them out of the expected result. “Clear the stale cache” already prescribes a repair; “show this eligible record in this search” describes behavior that an investigation can examine.
Establish the expected contract
Confirm who should see the record and when. Search may intentionally exclude some records or expose them after an agreed indexing delay. The direct URL and search might also apply different access rules.
Ask the behavior owner to resolve that ambiguity. Record the agreed visibility condition and timing expectation before writing an assertion. A test that demands immediate search visibility cannot establish a defect if the accepted contract permits a delay.
Use the same identity for comparisons where possible. If an administrator opens the record while another user searches, preserve that distinction in the report. Do not quietly turn two different permission contexts into one supposedly identical request.
Build the smallest repeatable sequence
Reduce the report to concrete actions:
- Prepare a known record and user with the relevant permissions.
- Create or identify the record through the stated route.
- Record the creation time and the search query.
- Perform the search under the specified identity.
- Compare the actual result with the agreed visibility contract.
Include pagination, filters, and ordering when they affect whether the record appears. Record the observation time relative to creation. Repeating a search after the problem has disappeared may provide a control, but it does not reproduce the earlier failure.
Name the environment, relevant revision, fixture, and command or user action. Keep the packet small enough that someone else can follow it without reconstructing the entire incident history.
Choose fixtures that distinguish explanations
Use controlled records that vary one relevant condition at a time. Compare a newly created record with an older eligible record. Compare an authorized user with a user who should not see it. Search for a known matching name and a known nonmatching name.
State the expected outcome for each. The unauthorized case should remain excluded after the repair; making every record visible would solve the observed absence by breaking another contract.
Keep production identities, credentials, and sensitive fields out of the fixture. If a particular data shape matters, preserve that relationship in a sanitized example. Record where the substitution may limit what the reproduction establishes.
Check that the test fails for the reported reason
A failing check needs an explanation. Confirm that it reaches the search path, creates or selects the intended record, and compares the relevant result. An authentication failure, unavailable service, or malformed fixture can make a test fail before it exercises the bug.
Avoid a check that merely proves your guessed implementation exists. Asserting that a cache-clearing helper was called says little about whether the eligible record becomes searchable.
For a reproducible defect, keep the reproduction separate from the repair. The same behavioral assertion should fail against the original behavior and pass after the change. Preserve meaningful controls so the passing result cannot come from deleting the filter or weakening the expectation.
Use logs to narrow the explanation
Connect the user action to relevant requests or jobs through correlation identifiers and timestamps. Compare the same path before and after a proposed change. Retain response categories and durations that help distinguish causes.
A generic provider error followed by a successful retry does not establish why the first attempt failed. A timeout, throttling response, and malformed request call for different investigations. More retries can hide the symptom while increasing load or repeating an invalid operation.
Ask what observation would separate the remaining hypotheses. Identify the missing response category or stage, and request that evidence. Redact sensitive fields while preserving the relationships needed to follow the sequence.
Keep unavailable reproduction visible
Some failures depend on data volume, timing, permissions, or infrastructure that the local environment cannot represent. State that limit precisely: which condition is missing, which observations are available, and what a local check could establish.
A bounded mitigation may still be appropriate. Record its intended effect, how it will be monitored, what would trigger stopping or recovery, and who owns the unresolved diagnosis. Describe it as mitigation while the cause remains unproved.
Do not replace missing evidence with “fixed locally.” A local success establishes only the case actually observed. Name the next environment or instrumented path needed to test the original report, with an owner and follow-up point.
Return a proof record the reviewer can inspect
The handoff should contain the reproduction sequence, expected and actual behavior, fixture and environment references, relevant evidence, and the proposed explanation. Add the changed files and checks required for a repair decision.
Separate checks that are proposed from those actually observed. For observed checks, record the revision and result; for missing checks, record the gap and next owner. Include the adverse cases that must continue to hold.
Close the investigation when the explanation fits the evidence and the repair addresses the stated mismatch without breaking its controls. If that bar is unmet, keep the uncertainty explicit so the next person can continue from what is known.
The Agentic Developer Interview includes Reproduction First and Log-Based Root Cause cards covering failing reproductions, evidence-linked explanations, and unresolved failure modes.