Debugging
Reading a diagnosis
What each verdict claims, what the evidence list is for, and where a run stopped short.
The diagnosis panel opens on the right when a debug turn is dispatched and fills in as the run works. Its top line is a verdict, and the four verdicts make genuinely different claims; it is worth knowing which one you are looking at before you act on the rest.
The four verdicts
| Verdict | What it claims |
|---|---|
| Root cause found | The fault was traced to a specific place in the source and confirmed with evidence. The strongest claim available. |
| Narrowed down | The search made real progress but did not confirm a single cause. Read the summary and the ruled-out list; a follow-up turn usually finishes the job. |
| Couldn’t reproduce | The described failure did not occur here. This is a successful outcome, not an error: it points at the environment, the build, or a missing step in the reproduction. |
| Needs more from you | A specific piece of information is missing. The summary names it; reply in the composer and the run continues from where it stopped. |
wr_ptr is compared before the increment, so the FIFO reports full one entry late.
rtl/fifo.sv:47 · signal full
Evidence (3)
waveform · t = 340 ns
wr_ptr=8 rd_ptr=0 full=0 push=1
Narrowed down is also the fallback
If a run finishes without filing a structured report, its answer is presented as Narrowed down with a note explaining that. That is deliberate; an unstructured answer must never be dressed up as a confirmed root cause. If you see the note, treat the content as a lead rather than a conclusion.
The root cause block
Under the summary sits the location: file, line and the signal involved, plus an explanation of the mechanism. A good one names a mechanism rather than a symptom. "full asserts one cycle late" is a symptom; "full is computed from the pre-increment pointer, so it only becomes true on the cycle after the entry that filled the FIFO" is a cause.
Evidence
Each entry is a fact that was actually read, with its source attached: a waveform reading at a specific time, an excerpt from a simulation or synthesis log, a lint finding, or a static check. Cross-check one or two of them against the artifacts on the turn; they are there so you can.
- Waveform entries carry a time and the values of the signals at that time.
- Log entries carry the excerpt they were drawn from.
- Static findings carry a confidence level, because they are pattern matches over the source rather than the result of elaborating the design. See Static checks.
Ruled out, and also noticed
Two lists sit under the evidence and are easy to skip; both are worth reading.
- Ruled out records theories that were tested and eliminated, and how. It is carried into the next turn's context, which is what stops a follow-up from paying to re-run the same investigation.
- Also noticed collects problems found along the way that are not the bug you asked about. They are reported rather than fixed, because widening the change set is not the run's call to make.
The simulation verdict
Alongside the diagnosis you get the result of the last simulation the run performed. It is reported as passed, failed, unknown, or hung.
| Verdict | Meaning |
|---|---|
| Passed | The testbench reported success by its own conventions. |
| Failed | The testbench reported a failure that nothing in the log refutes. |
| Unknown | The log did not follow a recognisable pass or fail convention. Reported honestly rather than optimistically called a pass. |
| Hung | The simulation never finished. Usually a stuck state machine or a clock that stopped toggling, which is itself a diagnosis rather than a tool error. |
Note
A self-checking testbench that prints something like Mismatches: 0 in 455 samples is read as a pass, not a failure. The word next to the number does not decide the verdict; the number does.
What to do next
- Root cause found, fix attached. Read the diff and apply it. See Applying a proposed fix.
- Narrowed down. Reply with whatever the summary says would settle it; the workspace and everything learned so far are still there.
- Could not reproduce. Check the reproduction steps and whether the failing testbench was included in what you uploaded.
- The run stopped at a ceiling. The partial diagnosis is kept and shown. See When a run stops early.