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 compiled and run, so the agent does need to edit and simulate. It does that in a throwaway copy of your project. Your files are byte-for-byte untouched for the whole run, and what survives at the end is a diff waiting for your decision.
The practical consequence: a debug run that crashes leaves nothing half-applied behind. There is no partial state to clean up, because the state was never yours to begin with. 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.
How the run works through the problem
The order matters, and it is the order a careful engineer would use. Knowing it helps you read the transcript and tell a run that is making progress from one that is stuck.
- Reproduce. Run the failing case and see the failure first-hand. If it cannot be reproduced, that is reported honestly rather than papered over with a guess.
- Localise. Find the first cycle where reality diverges from what should happen; that is rarely the cycle where the error message printed, and the gap between the two is usually where the bug lives.
- Hypothesise, then test. One theory at a time, each with a statement of what evidence would confirm or kill it.
- Confirm at the source. "Signal X is wrong at t=340" is a symptom; "line 47 assigns X from the pre-increment value" is a root cause.
- Fix minimally, then re-verify. The smallest change that addresses the cause, followed by a re-run of the failing case. A fix nobody re-simulated is a guess, and it is labelled as one.
Rules the run is held to
The obvious way to make a failing test pass is to delete the test. That is the single biggest risk in a feature like this, so it is not left to good intentions.
- Assertions and checks are never removed, weakened or commented out to make a failure go away. The change set is scanned for exactly that independently of what the run reports, and anything found is shown on the Apply button.
- The testbench is not rewritten to accommodate a broken design. Correcting genuinely wrong testbench timing is allowed, and when it happens it is called out explicitly.
- Unrelated code is not refactored, renamed or reformatted. Every extra diff line is a line you have to review.
- A root cause is not claimed without evidence. A narrowed-down answer with honest findings is preferred over a confident wrong one.
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 | Icarus Verilog. Designs written for another simulator are not rewritten to suit it; 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 every waveform tool works on it.
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.