rtl-bug-repro

name	rtl-bug-repro
description	Reproduce an RTL bug with a minimal TB and isolate root cause via waveform diff — 'reproduce this bug', 'minimal repro TB', regression failure isolation.
user-invocable	true
argument-hint	[bug-id | --failing-test <path>]
allowed-tools	Bash, Read, Write, Edit, Task, Grep, Glob

Reproduce 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).

<Use_When>

• A bug has been reported with a failure log or a failing test case.
• A simulation failure needs root cause analysis before an RTL fix is attempted.
• A regression failure needs isolation to a specific module. </Use_When>

<Do_Not_Use_When>

• The bug is in the testbench, not in RTL — fix the testbench directly.
• The root cause is already known — proceed to RTL fix.
• The bug is a synthesis issue — use rtl-synth-check instead. </Do_Not_Use_When>

<Why_This_Exists> Debugging 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. </Why_This_Exists>

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.

| Path | Role | |------|------| | `templates/repro-tb-template.sv` | Minimal TB scaffold: clock/reset gen, DUT instantiation, stimulus, pass/fail assertion. | | `scripts/vcd_diff.py` | Cycle-by-cycle VCD comparison — identifies first divergence between two waveform files. | | `references/bug-repro-conventions.md` | Naming rules, output schema (repro_tb.sv / root_cause.md), length guidance, anti-patterns. | | `examples/` | Worked example `bug-042-cabac-bypass/`: minimal confirmed-repro TB + `root_cause.md` per the conventions schema. |

<Responsibility_Boundary>

• Scripts handle deterministic waveform work: vcd_diff.py identifies the exact divergence cycle and signal path between two VCD files.
• LLM handles interpretive content: root cause hypothesis, signal trace narrative, suspected RTL location, and minimal stimulus design.
• Contract surface: root_cause.md structure documented in references/bug-repro-conventions.md. </Responsibility_Boundary>

1. Read the bug report or failing test log to understand the symptoms. 2. 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. 3. Read `skills/rtl-bug-repro/references/bug-repro-conventions.md` for naming, TB structure, and `root_cause.md` schema. 4. 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. 5. 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. 6. Write `sim/bugs/{bug_id}/root_cause.md` with: symptom, first failure cycle, signal trace table, suspected RTL file and line, clock/reset context.

Apply steps 1-6 to every bug ID requested — do not stop after the first.

<Tool_Usage> Waveform analysis (when no golden VCD for diff):

Task(subagent_type="rtl-agent-team:waveform-analyzer",
     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.")

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: 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.")

</Tool_Usage>

Regression test `test_cabac_bypass` fails at cycle 247; waveform shows output divergence in the bypass path. skills/rtl-bug-repro/examples/ `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`. No golden VCD available; only the failing test log and the module source exist. skills/rtl-bug-repro/examples/ `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. Bug affects three modules; regression isolates failure to the AXI-Stream bridge boundary. skills/rtl-bug-repro/examples/ 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.

<Escalation_And_Stop_Conditions>

• 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.
• Root cause requires architecture knowledge → include rtl-architect in the analysis task.
• Bug affects multiple modules → document all affected signal paths in root_cause.md and flag as systemic.
• VCD file is unreadable or corrupt → report the parse failure; do not fabricate waveform values. </Escalation_And_Stop_Conditions>

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.

<Final_Checklist>

• Existing waveform analyzed for first divergence point before writing the TB.
• Minimal repro TB written using templates/repro-tb-template.sv scaffold.
• TB confirmed to reproduce the failure (run_sim.sh exit code 0 + failure assertion fires).
• sim/bugs/{bug_id}/root_cause.md written with signal trace and suspected RTL location.
• RTL source not modified.
• Repro TB is small enough to add to the regression suite. </Final_Checklist>