Debug Playbook Checklist: Repro, Fix, and Sign-Off

The senior debug checklist

Before closing any debug ticket, walk this checklist. It prevents 'fixed' bugs that reproduce on the next seed.

[DEBUG][SENIOR][UVM] full playbook checklist

CAPTURE (before any edit):
  [ ] exact seed and plusargs recorded
  [ ] failure bucket classified
  [ ] log saved at triage verbosity
  [ ] first failing evidence identified

REPRODUCE:
  [ ] same seed fails twice identically
  [ ] minimal test/sequence isolates failure
  [ ] bucket first move re-confirms root cause

FIX:
  [ ] fix addresses root cause (not symptom)
  [ ] no unrelated TB changes in same commit

VALIDATE:
  [ ] failing seed now passes
  [ ] smoke suite still passes
  [ ] fix documented in commit message

#!/bin/bash
# senior repro capture script
TEST=$1 SEED=$2
simv +UVM_TESTNAME=$TEST +ntb_random_seed=$SEED \
     +UVM_VERBOSITY=UVM_MEDIUM -l repro_${TEST}_${SEED}.log
echo "TEST=$TEST SEED=$SEED" > repro_${TEST}_${SEED}.meta

Key takeaways

• Never edit before capture — reproducers are senior debug currency.

• Minimal repro accelerates review and prevents fix regression.

• Validate the exact failing seed after every fix.

Common pitfalls

• Fixing without repro — bug 'vanishes' and root cause unknown.

• Closing ticket after one passing seed without smoke rerun.

• Mixing multiple fixes in one commit — untraceable regressions.

Minimal reproducer techniques

Reduce scope systematically: full test → single sequence → single transaction → single field.

Reduction ladder

1. Run with same seed — confirm identical failure signature.

2. Disable optional agents/scoreboards — does failure persist?

3. Replace random sequence with directed one-transaction sequence.

4. Hardcode the failing field value from first mismatch log.

5. Document the smallest failing test for the ticket.

class repro_one_txn_seq extends uvm_sequence #(my_item);
  task body();
    my_item req = my_item::type_id::create("req");
    start_item(req);
    req.addr = 32'hDEAD_BEEF;  // from first mismatch log
    req.data = 32'h0000_0001;
    finish_item(req);
  endtask
endclass

Sign-off and handoff

[DEBUG][SENIOR][UVM] ticket handoff template

bucket:        CHECKING
root cause:    monitor byte-swap on wide data
fix:           pack() bit ordering in mon.sv
repro:         stress_crc_test seed 847291
validated:     seed 847291 pass + nightly smoke pass
follow-up:     add directed seq for wide-data corner

• Attach repro meta file (test, seed, plusargs) to every ticket.

• Link commit hash to validation log in ticket comment.

• Escalate to RTL only after TB bucket first moves exhausted.

• Add a directed test or assertion guard when fix closes a hole.

# post-fix validation
simv +UVM_TESTNAME=stress_crc_test +ntb_random_seed=847291 -l post_fix.log
grep -c UVM_ERROR post_fix.log  # expect 0

Key takeaways

• Minimal repro is the fastest path to reviewable fixes.

• Ticket handoff quality separates senior from junior debug.

• Every fix should leave the TB stronger — directed test or guard.

Common pitfalls

• Skipping smoke rerun because 'it's a one-line fix'.

• Handoff without seed — next engineer restarts triage from zero.

• Closing prediction bugs without adapter/predictor regression test.