Debugging
Debug mode
Point the agent at a design that misbehaves and get back a diagnosis with evidence.
Debug mode is for the design that already exists and is already wrong. You hand over the code, say what you expected and what actually happened, and you get back a diagnosis: what is broken, which line causes it, and the evidence that says so. A fix comes with it, but nothing touches your files until you accept it.
What you get back
| Part of the answer | What it contains |
|---|---|
| Diagnosis | A verdict, a one-paragraph summary, and where the fault lives: file, line and signal. |
| Evidence | Specific times and signal values read out of a waveform, log excerpts, and findings from the static checks. |
| Ruled out | Hypotheses that were tested and eliminated, so a follow-up turn does not pay to repeat them. |
| Proposed fix | A diff you can read, apply in one click, or turn down; it is a proposal, not a change already made. |
Nothing is edited until you say so
A diagnosis is worth much more when the fix behind it has actually been built and run, so a debug run does compile and simulate; it just never does it to your files. Your project is untouched for the whole run, and what you are left with at the end is a diff waiting for your decision.
The practical consequence: a debug run that fails part way leaves nothing half-applied behind, so there is never a partial state to clean up. See Applying a proposed fix for what happens when you accept one.
Two ways in
- 1
From an existing chat
If a chat already produced code, a Debug toggle appears next to the composer. Switch it on, describe the problem, and send. The module and testbench from the most recent turn that produced code are carried across for you; you do not re-upload anything. The toggle only shows up once there is code to work on.
- 2
From a cold start
On the New chat screen, pick the Debug tab and upload the project as a zip. Debugging from scratch necessarily means bringing the code, so this tab rides on the same project upload that Existing project uses.
What a good debug run looks like
A debug run works the way a careful engineer would, and the transcript reflects that. It is worth knowing the shape so you can tell a run that is making progress from one that is circling:
- It reproduces the failure first. If it cannot, that is reported honestly rather than papered over with a guess.
- It looks for the first moment things go wrong, which is rarely the moment the error was printed. The gap between the two is usually where the bug lives.
- It takes one theory at a time and says what would confirm or kill it, so the ones it eliminates come back to you as a list rather than as wasted budget.
- It confirms the cause at the source. "Signal X is wrong at t=340" is a symptom; a named line that produces it is a root cause, and only the second one is claimed as such.
- It re-runs the failing case after the fix. A fix nobody re-simulated is a guess, and it is labelled as one on the proposal card.
What a fix will never do
The obvious way to make a failing test pass is to delete the test, and that is the single biggest risk in a feature like this. It is not left to good intentions:
- Checks are never removed or weakened to make a failure go away. Every proposal is examined for that regardless of what the run says it did, and anything found is shown on the Apply button before you can click it.
- The testbench is not rewritten to accommodate a broken design. Fixing genuinely wrong testbench timing is allowed, and it is called out when it happens.
- Nothing unrelated is touched. No refactoring, renaming or reformatting; every extra diff line is a line you have to review.
- A root cause is not claimed without evidence. An honest "narrowed down" beats a confident wrong answer, and the verdict says which one you have.
Requirements and limits
| Requirement | Detail |
|---|---|
| Language | Verilog and SystemVerilog. VHDL is not supported in Debug mode. |
| Mode | Agent mode. The Agent / Plan switch is replaced by a fixed label, because the pipeline flow cannot run this. |
| Tools | A debug run picks its own tools, so the Tools switches are shown disabled with the reason. |
| Credit | A debug run needs a slightly higher minimum balance than a normal run, because starting one on the last few cents guarantees it stops mid-investigation. |
| Simulator features | A design written against a specific commercial simulator's extensions may not run here. It is not rewritten to suit ours; the run says so and reasons from the source and the static checks instead. |
Board failures are outside what this can settle
Timing closure and constraints need a vendor toolchain that this run does not have. You can absolutely describe a failure you saw on hardware, and the answer will report what the static checks found; it will also say plainly that timing needs your own tools rather than dressing a heuristic up as the answer. A capture from the board is a different story: an ILA or SignalTap export is just a waveform, and everything on this page that reads a waveform reads that one too.
Debug is a property of the turn, not the chat
Building a module, debugging it and then going back to adding features is one conversation. Each turn carries its own intent, so the diagnosis panel appears for the debug turn and the code panel comes back for the next build turn. You do not need a fresh chat to switch.
Note
One thing this changes on the turn card: a debug turn never shows a "3 files modified" line. That count would describe a proposal, and reading it as work already applied to your project is precisely the misunderstanding this mode is built to avoid.