Prerequisites
- A failure log or failing
.vcd/.fst waveform from a previous simulation run.
- RTL source for the suspected module under
rtl/**/*.sv.
If prerequisites are missing: WARNING — recommend running the failing regression test first to obtain a waveform. Proceed with available artifacts; the orchestrator adapts scope.
Apply steps 1-6 to every bug ID requested — do not stop after the first.
Minimal TB authoring and confirmation:
Task(subagent_type="rtl-agent-team:func-verifier",
prompt="Write sim/bugs/BUG-042/repro_tb.sv that reproduces the CABAC bypass mode failure at cycle ~250. Minimize stimulus to the essential sequence. Use: i_/o_ port prefixes, sys_clk, sys_rst_n, u_dut instance, logic types only. Scaffold: {plugin_root}/skills/rtl-bug-repro/templates/repro-tb-template.sv. Run: scripts/run_sim.sh --sim iverilog --top repro_tb --outdir sim/bugs/BUG-042 --trace rtl/cabac_encoder/cabac_encoder.sv sim/bugs/BUG-042/repro_tb.sv. Confirm reproduction.")
Output
sim/bugs/{bug_id}/repro_tb.sv — minimal reproduction testbench, confirmed to reproduce the failure.sim/bugs/{bug_id}/root_cause.md — root cause analysis: symptom, first failure cycle, signal trace, suspected RTL location.sim/bugs/{bug_id}/repro_tb.vcd (or .fst) — waveform from the reproduction run.
1---2name: rtl-bug-repro3description: Reproduce an RTL bug with a minimal TB and isolate root cause via waveform diff — 'reproduce this bug', 'minimal repro TB', regression failure isolation.4---56<Purpose>7Reproduce a reported RTL bug with the minimal stimulus, isolate the root cause via waveform analysis, and produce a confirmed reproduction testbench. Outputs: `sim/bugs/{bug_id}/repro_tb.sv` (minimal TB that reproduces the failure) and `sim/bugs/{bug_id}/root_cause.md` (signal trace, first failure cycle, suspected RTL location).8</Purpose>910<Use_When>11- A bug has been reported with a failure log or a failing test case.12- A simulation failure needs root cause analysis before an RTL fix is attempted.13- A regression failure needs isolation to a specific module.14</Use_When>1516<Do_Not_Use_When>17- The bug is in the testbench, not in RTL — fix the testbench directly.18- The root cause is already known — proceed to RTL fix.19- The bug is a synthesis issue — use `rtl-synth-check` instead.20</Do_Not_Use_When>2122<Why_This_Exists>23Debugging without a minimal reproduction wastes time. Waveform analysis on the full regression is slow; a targeted minimal TB isolates the failure in minutes. `root_cause.md` documents the finding for the RTL engineer making the fix, and the repro TB can be added directly to the regression suite.24</Why_This_Exists>2526## Prerequisites2728- A failure log or failing `.vcd`/`.fst` waveform from a previous simulation run.29- RTL source for the suspected module under `rtl/**/*.sv`.3031If prerequisites are missing: WARNING — recommend running the failing regression test first to obtain a waveform. Proceed with available artifacts; the orchestrator adapts scope.3233<Assets>34| Path | Role |35|------|------|36| `templates/repro-tb-template.sv` | Minimal TB scaffold: clock/reset gen, DUT instantiation, stimulus, pass/fail assertion. |37| `scripts/vcd_diff.py` | Cycle-by-cycle VCD comparison — identifies first divergence between two waveform files. |38| `references/bug-repro-conventions.md` | Naming rules, output schema (repro_tb.sv / root_cause.md), length guidance, anti-patterns. |39| `examples/` | Worked example `bug-042-cabac-bypass/`: minimal confirmed-repro TB + `root_cause.md` per the conventions schema. |40</Assets>4142<Responsibility_Boundary>43- **Scripts** handle deterministic waveform work: `vcd_diff.py` identifies the exact divergence cycle and signal path between two VCD files.44- **LLM** handles interpretive content: root cause hypothesis, signal trace narrative, suspected RTL location, and minimal stimulus design.45- Contract surface: `root_cause.md` structure documented in `references/bug-repro-conventions.md`.46</Responsibility_Boundary>4748<Execution>491. Read the bug report or failing test log to understand the symptoms.502. Run `python3 {plugin_root}/skills/rtl-bug-repro/scripts/vcd_diff.py --actual sim/regression/{test}.vcd --expected sim/regression/{test}_golden.vcd` (`{plugin_root}` = plugin root resolved from `.rat/state/spawn-context.json`) to identify the first divergence cycle and originating signal. If no golden VCD exists, spawn `waveform-analyzer` (see Tool_Usage) to analyze the failing VCD directly.513. Read `references/bug-repro-conventions.md` for naming, TB structure, and `root_cause.md` schema.524. Spawn `func-verifier` (see Tool_Usage) to write `sim/bugs/{bug_id}/repro_tb.sv` using `templates/repro-tb-template.sv` as scaffold. The TB must: use `i_`/`o_` port prefixes, `{domain}_clk`/`{domain}_rst_n` names, `logic` types only, and `u_dut` for the DUT instance.535. Run the repro TB: `scripts/run_sim.sh --sim iverilog --top repro_tb --outdir sim/bugs/{bug_id} --trace rtl/{module}/{module}.sv sim/bugs/{bug_id}/repro_tb.sv`. Confirm the failure reproduces.546. Write `sim/bugs/{bug_id}/root_cause.md` with: symptom, first failure cycle, signal trace table, suspected RTL file and line, clock/reset context.5556Apply steps 1-6 to every bug ID requested — do not stop after the first.57</Execution>5859<Tool_Usage>60Waveform analysis (when no golden VCD for diff):61```62Task(subagent_type="rtl-agent-team:waveform-analyzer",63 prompt="Analyze sim/regression/test_cabac_fail.vcd. Find first divergence between actual and expected output. Identify originating module and signal path. Port signals use i_/o_ prefixes, clocks are {domain}_clk, resets are {domain}_rst_n.")64```6566Minimal TB authoring and confirmation:67```68Task(subagent_type="rtl-agent-team:func-verifier",69 prompt="Write sim/bugs/BUG-042/repro_tb.sv that reproduces the CABAC bypass mode failure at cycle ~250. Minimize stimulus to the essential sequence. Use: i_/o_ port prefixes, sys_clk, sys_rst_n, u_dut instance, logic types only. Scaffold: {plugin_root}/skills/rtl-bug-repro/templates/repro-tb-template.sv. Run: scripts/run_sim.sh --sim iverilog --top repro_tb --outdir sim/bugs/BUG-042 --trace rtl/cabac_encoder/cabac_encoder.sv sim/bugs/BUG-042/repro_tb.sv. Confirm reproduction.")70```71</Tool_Usage>7273<Examples>74<example index="1">75<scenario>Regression test `test_cabac_bypass` fails at cycle 247; waveform shows output divergence in the bypass path.</scenario>76<reference>examples/</reference>77<expected_output>`vcd_diff.py` reports first divergence at cycle 247 on `u_cabac_encoder.o_bin_val`; `func-verifier` writes a 40-line `repro_tb.sv` that reproduces in 300 cycles; `root_cause.md` identifies missing state reset in `bypass_ctx` register at `rtl/cabac_encoder/cabac_encoder.sv:183`.</expected_output>78</example>7980<example index="2">81<scenario>No golden VCD available; only the failing test log and the module source exist.</scenario>82<reference>examples/</reference>83<expected_output>`waveform-analyzer` reads the failing VCD and identifies the signal path without a golden reference; `func-verifier` writes minimal stimulus based on the identified divergence point; `root_cause.md` labels the hypothesis as "suspected" pending confirmation by the repro run.</expected_output>84</example>8586<example index="3">87<scenario>Bug affects three modules; regression isolates failure to the AXI-Stream bridge boundary.</scenario>88<reference>examples/</reference>89<expected_output>Repro TB instantiates only the two modules at the failing boundary; `root_cause.md` documents all affected signal paths and flags the issue as systemic per escalation rules.</expected_output>90</example>91</Examples>9293<Escalation_And_Stop_Conditions>94- Cannot reproduce with minimal TB → expand stimulus scope to the full failing test; note in `root_cause.md` that a minimal repro could not be isolated.95- Root cause requires architecture knowledge → include `rtl-architect` in the analysis task.96- Bug affects multiple modules → document all affected signal paths in `root_cause.md` and flag as systemic.97- VCD file is unreadable or corrupt → report the parse failure; do not fabricate waveform values.98</Escalation_And_Stop_Conditions>99100## Output101102- `sim/bugs/{bug_id}/repro_tb.sv` — minimal reproduction testbench, confirmed to reproduce the failure.103- `sim/bugs/{bug_id}/root_cause.md` — root cause analysis: symptom, first failure cycle, signal trace, suspected RTL location.104- `sim/bugs/{bug_id}/repro_tb.vcd` (or `.fst`) — waveform from the reproduction run.105106<Final_Checklist>107- [ ] Existing waveform analyzed for first divergence point before writing the TB.108- [ ] Minimal repro TB written using `templates/repro-tb-template.sv` scaffold.109- [ ] TB confirmed to reproduce the failure (`run_sim.sh` exit code 0 + failure assertion fires).110- [ ] `sim/bugs/{bug_id}/root_cause.md` written with signal trace and suspected RTL location.111- [ ] RTL source not modified.112- [ ] Repro TB is small enough to add to the regression suite.113</Final_Checklist>
babyworm