| name | debug |
| description | Triage a failing or misbehaving compiler test. Use this at the start of any debug session when a test is failing, a signal has a wrong value, a simulation mismatch appears, or a pass starts regressing and you need to choose the right artifact and workflow first. |
Step 1 - identify the failure mode
| Symptom | Start here |
|---|
| custom-sim vs Verilator output mismatch | read-vcd - find the first diverging signal or scope, then use trace-dfg-runtime or read-dfg on that cone |
| Signal has wrong or unexpected value | read-dfg - node --details, then deps, uses, or neighborhood |
| Need runtime evidence for how an op evaluated | trace-dfg-runtime |
| Entire struct or group of signals is zero | read-dfg - const_driven 0, then group or uses |
| Flop missing, wrong domain tag, or wrong reset | read-hierarchy - flops <path>, then check 06_flop_resolve_flops.txt |
| Module structure wrong (missing port, wrong hierarchy) | read-hierarchy - tree, then module <path> |
| Clock/reset domain error, CDC failure, domain propagation issue | debug-domains |
| Pass regression (worked before, broken now) | read-dfg - compare adjacent pass JSONs with diff; narrow to one node or cone when possible |
Step 2 - locate the debug artifacts
Artifacts live under the work directory used to reproduce the failure:
tests/<name>/work/static/debug_output/<top>/tests/<name>/work/custom-sim/debug_output/<top>/tests/<name>/work/custom-sim/output/
Key files:
- per-pass DFG:
NN_<pass_name>.json and .dot
hierarchy.json06_flop_resolve_flops.txt11_domains_propagate_flops.txt or 12_domains_propagate_flops.txtoutput/dfg_trace.jsonl when runtime DFG tracing is enabled- VCDs under
output/ or verilator/
Step 3 - narrow the first bad point
When the symptom is a wrong value or wrong structure:
- Find the first bad signal, scope, or pass.
- Prefer the smallest artifact that exposes the problem: a single node before a full cone, a single scope before the entire VCD.
- If static DFG shape looks right but the runtime value is wrong, switch to
trace-dfg-runtime.
Sub-skills
read-dfg - static DFG artifact inspection with node, nodes, deps, uses, neighborhood, and structural difftrace-dfg-runtime - runtime DFG evaluation tracing with --trace-dfg-node, --trace-dfg-cone, and --trace-dfg-opread-hierarchy - hierarchy.json inspection (tree, flops, find, clocks)read-vcd - waveform inspection and unified cross-sim diff (vcd_inspect.py, vcd_diff.py)debug-domains - domain/CDC pass workflow and sidecar schema
