babyworm/rtl-agent-team/rtl-p4s-bugfix-policy

RTL Bug Fix Policy

Mandatory 4-Step Sequence (per module)

1. Analyze → identify root cause and affected modules
2. Fix + Lint → modify RTL, run verilator --lint-only -Wall (max 3 lint rounds)
3. TB → create or update testbench (at least 1 test per modified module)
4. Functional Verification → run simulation, ALL tests must PASS

Each step can only proceed after the previous step is complete. Lint is a necessary condition, NOT sufficient — simulation is required.

Parallel UNIT_FIX Decision Tree

Verification-done marker created ONLY after ALL parallel fixes pass functional verification.

Phase 5→4 Feedback Mode

In feedback mode: lesson-learned recording is mandatory (not just recommended).

Escalation & Stop Conditions

• Lint fails 3 times → escalate to rtl-architect for design review
• Cannot write TB (no ref model) → write minimal self-checking TB, report ref model requirement to user
• Simulation fails after 2 fix iterations → escalate to waveform-analyzer + rtl-bug-repro skill
• Simulator not installed → eda-runner provides installation instructions

TB Signal Naming Convention

• dut.sys_clk, dut.sys_rst_n (clock/reset)
• dut.i_*, dut.o_* (input/output ports)
• TB check: ls sim/*/test_*.py sim/*/tb_*.sv 2>/dev/null

Advanced Rules

Integration bugs (multi-module):

• Both per-module unit TBs AND top-level integration TB needed
• Unit TBs: verify individual module I/O
• Integration TB: verify data flow between modules

When regression suite available:

• Recommended to re-run full regression after fix
• Use rtl-p5s-func-verify skill for multi-seed verification

Compound mode bugs (e.g., MODE_RECON):

• Test individual modes first, then compound mode tests, then mode transition scenarios

Final Checklist

• [ ] Bug root cause identified
• [ ] RTL fix complete
• [ ] Lint passed (verilator --lint-only -Wall, 0 errors)
• [ ] TB created or updated (at least 1 test per modified module)
• [ ] Bug reproduction scenario included as a test case
• [ ] Functional simulation executed (cocotb or verilator sim)
• [ ] All tests PASS
• [ ] Verification-done marker created (.rat/state/rtl-verify-done)
• [ ] TB signal naming convention followed
• [ ] Multi-module failures classified (UNIT_FIX vs INTEGRATION_FIX)
• [ ] Independent UNIT_FIX modules fixed in parallel (not sequentially)
• [ ] All parallel fixes passed functional verification before verify-done marker