The goal is to restore the user's originally failing task and to make the conclusion consistent with what is actually proven.
Reproduce the Problem
- Distinguish the observable symptoms, expected behavior, and attribution guesses in the report. What the reporter provides is valuable clues; guesses need experimental verification.
- Confirm the repository to be modified, the actual workspace, the version/commit, and the startup entry point; reference repositories serve only as references. Record the environment, effective configuration, input scale, and historical state relevant to the problem; for sensitive values, record only whether the configuration exists or a redacted identity.
- Try to reproduce from the user entry point, and save the exact steps, errors, and expected results. When an automated regression that fails before the fix can be established safely, prioritize establishing it; simple problems do not require generating extra documentation.
Verify the Cause
Do not only look for evidence that supports the first explanation. Design experiments for competing hypotheses, changing one key condition at a time when possible. Locate the actual difference along the call chain, configuration precedence, state lifecycle, and data scale.
For complex investigations, maintain a table in the task working directory:
| Hypothesis | Distinguishing experiment | Actual result/evidence location | Status | Applicable environment and version |
|---|
Exclusion records are used to avoid repeated exploration; hypotheses can be reopened after the version, input, or conditions change. The temporary disappearance of the problem does not equal a fix. After the first cause is confirmed, still check from the original entry point whether there are additional overlapping causes.
When full reproduction is temporarily impossible, continue reading the relevant code and logs, narrow the environmental differences, or add necessary diagnostics. Code paths and targeted failing tests can prove a local defect, but cannot pass as reproduction in the user's environment. When the user explicitly requires "reproduce before modifying," maintain that execution boundary. Do not infinitely increase load or expand the scope of modification to force reproduction.
Fix and Retest
Modify only the cause supported by evidence, and preserve unrelated existing behavior. Record independent old problems as follow-up items; regressions introduced this time should be fixed.
After the fix, rerun the original entry point, the original key conditions, and the failing input; do not substitute smaller data, another entry point, or a new configuration for the original acceptance. Add checks for adjacent paths related to the change, such as recovery, cancellation, boundary inputs, or configuration overrides; do not expand tests in full by default.
Choose tests according to the boundary to be proven: use deterministic tests for pure logic; for timeouts/races, control the clock or upstream; when there are actual changes in a real provider, system, or release entry point, add corresponding real verification. Accurately state the scope covered by simulated tests and actual runs respectively.
Assert user-observable results, persisted state, or real artifacts, and avoid only checking for "success" in the AI response. New regression tests should be able to fail under the old behavior or under a controlled regression.
Delivery
First state whether the original workflow is restored, then give: the root cause chain, the modifications, the before-fix/after-fix evidence, and unverified conditions. Clearly distinguish actual test confirmation, code path confirmation, inference, and non-reproduction. Commands that were not run cannot count as verification.
If reproduction disappears but there is no causal evidence, report "not reproduced this time, root cause unconfirmed"; if only a local regression passes, report its scope. When new evidence overturns a previous judgment, explicitly correct it.
For complex investigations, reproduction, hypothesis experiments, and same-condition retests can be saved as troubleshooting records .