Part 9 answers: How do I close the bug for good?
A bug is not fixed when the test passes; it is fixed when the cause is gone, the fix is proven, and the next bug like it would be caught earlier. This part covers all three, plus the root-cause and escape analysis that make a team better after every bug.
Tell a fix of the cause from a fix that hides the symptom.
Prove a fix with a repro, a seed sweep and a regression test.
Run an honest root-cause and escape analysis.
7 lessons, about 82 min
The part on one page, taken from each lesson's Remember box.
Fix the Cause, Not the Symptom
Every candidate fix makes the failing seed pass. That is the entry ticket, not the evidence.
Size a fix to the specification of the input, never to the values your tests happened to make.
Before choosing between two fixes, find the input where they disagree, write a test for it and run both.
Rule of thumb: a fix is the cause fix only if it holds for every input the specification allows.
Proving the Fix
Same command as the repro first, in both simulators. Then the shrunk repro, which tests the mechanism without the noise.
A sweep means nothing without the same sweep before the fix. Sort both by signature and count how often the bug's condition was reached.
When the claim is "for every input", sampling cannot prove it. A short formal check on the real RTL can, in seconds.
Rule of thumb: a fix is proven when every rung that could have failed it was run, before and after, with the counts written down.
The Regression Test That Pins the Bug
A pin is proven at three points: it passes on the parent commit, fails on the guilty commit, and passes on the fix.
A seed reaches the bug by luck. A directed test states the condition, so a change to the random test cannot take it away.
Run the pin where it can fail. A test that passes on the buggy commit in your nightly simulator pins nothing.
Rule of thumb: do not close a bug until a test that names its condition fails on the commit that caused it.
The Assertion That Would Have Caught It
Write the assertion from the specification of the rule, never from the fix or the buggy line: then it means the same before and after.
Prove it three ways: it fires on the buggy commit at the cause, it is silent on the fix across the regression, and a cover shows it was not vacuous.
Check what your tools check. Icarus 13 compiles no concurrent SVA; Yosys 0.69 ignores bind; Verilator is two-state, so X checks never fire there.
Rule of thumb: an assertion you have not seen fail, and seen not vacuous, protects nothing.
Root-Cause Analysis, Done Honestly
Every why needs evidence you can show: a run, a diff, a log line. An answer you cannot show is a guess; mark it and go and get the evidence.
Ask two chains: why did the bug happen, and why did it get through. They fork at the commit and usually end at different causes.
Stop at something you can change and check. "Be more careful" fails both tests; "block a commit that adds a failing run" passes them.
Rule of thumb: a root cause is something you can change, and you have shown that changing it would have stopped this bug.
Escape Analysis
A bug gets through one of four gates: not planned, planned but never reached, reached but not checked, checked but nobody acted. Name the gate.
Prove the gate with a run at the bad commit: a coverage count of zero, a check that would have fired, a regression diff nobody read.
Each plan change must be measurable and must catch this bug when you put it back. One test per escape pins one bug; a goal per gate catches its siblings.
Rule of thumb: replay verification as it was at the bad commit; today's tests tell you nothing about why it escaped.
The Bug Write-Up That Teaches the Team
The report asks someone to act; the write-up records the answer after the fix is proven. Write it for a reader who was not there.
Every claim carries the command that shows it. Exposure says exactly which inputs and which versions are affected, not "long transfers".
End with one lesson that changes how people write new code, plus the checks added. If nothing generalises, say why.
Rule of thumb: if a reader of the write-up could make the same mistake tomorrow, the write-up is not finished.
Practice question: Counter with wrap and saturate modes
Code lab: DMA control FSM
Practice question: Random stability and post-repair safety
Practice question: Debugging rare seed failures in regression
Code lab: Bind assertion
Interview: run a mock interview on this topic