bjwanneng/veriflow-cc / src/claude_skills/vf-rtl
vf-rtl
Verifiederror_recovery.md
View on GitHub# Error Recovery Procedure
This file is loaded by the main session ONLY when simulation fails.
Read this file with the Read tool, then follow the steps below.
---
## Step 0: Data Collection + Bug Type Classification (MANDATORY)
Before forming ANY root cause hypothesis, collect objective diagnostic data.
### 0a. Collect data
1. Read `logs/sim.log` — extract all `[FAIL]` lines with cycle numbers
2. Extract VCD path and top module:
```bash
source "$PROJECT_DIR/.veriflow/eda_env.sh"
cd "$PROJECT_DIR"
TOP_MODULE=$($PYTHON_EXE -c "
import json
spec = json.load(open('workspace/docs/spec.json'))
for m in spec.get('modules', []):
if m.get('module_type') == 'top':
print(m['module_name']); break
")
VCD_FILE=$(ls -t workspace/sim/*.vcd 2>/dev/null | head -1)
```
3. Run vcd2table golden model diff:
```bash
if [ -f workspace/docs/golden_model.py ] && [ -n "$VCD_FILE" ] && [ -f "$VCD_FILE" ]; then
$PYTHON_EXE "${CLAUDE_SKILL_DIR}/analysis/vcd2table.py" \
"$VCD_FILE" \
--sim-log logs/sim.log \
--golden-model workspace/docs/golden_model.py \
--module $TOP_MODULE \
--output logs/wave_diff.txt 2>&1 | tee logs/vcd2table.log
elif [ -n "$VCD_FILE" ] && [ -f "$VCD_FILE" ]; then
$PYTHON_EXE "${CLAUDE_SKILL_DIR}/analysis/vcd2table.py" \
"$VCD_FILE" \
--sim-log logs/sim.log \
--module $TOP_MODULE \
--output logs/wave_table.txt 2>&1 | tee logs/vcd2table.log
else
echo "[VERIFY] No VCD file — relying on sim.log only."
fi
```
4. Read the diff/table output — identify first divergence cycle and signal
5. **Cocotb FIRST DIVERGENCE (primary diagnostic)**: If cocotb test_internal_signals
reported a FIRST DIVERGENCE, use that as the PRIMARY diagnostic. The divergence
cycle and signal name pinpoint exactly where the RTL first differs from golden model.
Do NOT guess the root cause — trace from the divergence point backward through the
datapath. Example: if divergence is at cycle 14, signal `u_expansion.w_reg[0]`,
the bug is in expansion logic, likely in the round BEFORE cycle 14.
6. **Expected per-cycle trace from golden_model.py**: SKILL.md Stage 3 generates
`logs/expected_trace_golden.md` from the golden model. This table shows
the *exact* register values the RTL should hold each cycle. Compare them
against the VCD-derived table from step 4 to read off the divergence:
```
expected[cycle=N][reg_name] = X (from logs/expected_trace_*.md)
actual [cycle=N][reg_name] = Y (from logs/wave_diff.txt or VCD)
```
If a register matches `expected` until cycle K and diverges at cycle K+1,
the buggy `always @(posedge clk)` block is the one that drives that register.
### 0b. Classify bug type
| Type | Symptom | Direction |
|------|---------|-----------|
| **A. Computation** | Output wrong (not zero) or zero when expected non-zero | Trace datapath: formula, condition, index |
| **B. Timing** | Correct value but wrong cycle | Check pipeline alignment, register stages |
| **C. Protocol** | valid/ready timing violates handshake spec | Check handshake protocol, FSM transitions |
| **D. Initialization** | First output offset by constant | Check register init values, algorithm IV loading |
| **E. Expansion** | W/message scheduling output wrong from specific round | Trace expansion formula: bit-slice widths, P0/P1 inputs |
**Classification rule — read the value, then decide**: Match the symptom to a
type using the divergence values; do NOT preselect one based on the design's
clock topology.
- `actual` is `x`/`z` or `actual==0` while `expected!=0` → Type **D** (init/uninitialized).
- `actual` matches `golden_trace[cycle ± offset]` for some small `offset` →
Type **B** (timing/pipeline). This is the SM3 failure mode and is common in
pipelined hash/cipher cores even when there is a single clock domain — do
NOT skip Type B hypotheses because the design is single-clock.
- `actual` is a plausible-looking but wrong value, and no nearby golden cycle
matches it → Type **A** (computation).
- valid/ready or handshake protocol misbehaviour → Type **C**.
- Output is off by a constant offset from cycle 0 → Type **D** (algorithm IV
not loaded).
- Trace shows divergence starting at a specific round of a message expansion
→ Type **E** (expansion formula / bit-slice bug).
If `timing_diagnostic.py` already classified the divergence (B_late/B_early
vs A vs D), trust its classification — it has the golden trace and the
spec.json timing_contract to back the decision.
---
## Step 1: Diagnose
- Read the error output from the failed stage
- Read the relevant RTL files from `workspace/rtl/`
- Reference `bug_patterns.md` for a catalog of known bug patterns
---
## Step 1.5: Structured Root Cause Analysis (MANDATORY)
Before modifying ANY file, complete the analysis and write to `logs/stage_journal.md`.
### 5-point root cause analysis
1. **Error location**: Which `[FAIL]` line? Which cycle? Which signal? If
`logs/expected_trace_*.md` exists, also note `expected[cycle][signal]`
versus the actual value — the gap is the bug's signature, not just its symptom.
2. **Signal trace**: Which module drives it? Which `always` block?
3. **Root cause hypothesis**: Exact RTL line that is wrong.
4. **Minimal fix plan**: File, lines, exact change.
5. **Impact scope**: Which other signals/modules affected?
If you cannot form a hypothesis, STOP and ask the user. Do NOT guess-and-fix.
---
## Step 2: Fix
Common error patterns:
| Error Pattern | Cause | Fix |
|--------------|-------|-----|
| `cannot be driven by continuous assignment` | `reg` used with `assign` | Change to `wire` or use `always` |
| `Unable to bind wire/reg/memory` | Forward reference or typo | Move declaration or fix typo |
| `Variable declaration in unnamed block` | Variable in `always` without named block | Move to module level |
| `Width mismatch` | Assignment between different widths | Add explicit width cast |
| `is not declared` | Typo or missing declaration | Fix typo or add declaration |
| `Multiple drivers` | Two assignments to same signal | Remove duplicate |
| `Latch inferred` | Incomplete case/if without default | Add default case or else branch |
Fix rules:
- Only modify files that have issues
- Preserve original coding style and design intent
- Do NOT change module interfaces (ports) — Interface Lock
- Do NOT add/remove functionality
- Make minimal changes, fix one error at a time
- **Debug budget**: 3 fix-and-retry cycles max, then STOP and ask user
After fixing, re-run simulation to verify.
---
## Step 3: Log recovery to journal
```bash
printf "\n### Recovery: <stage_name>\n**Timestamp**: $(date -Iseconds)\n**Attempt**: <N>\n**Error type**: <syntax|logic|timing>\n**Fix summary**: <description>\n**Result**: <PASS|FAIL|PENDING>\n" >> "$PROJECT_DIR/logs/stage_journal.md"
```
---
## Retry Policy
1. **1st fail**: Fix RTL, retry simulation
2. **2nd fail**: Rollback to codegen and re-run from Stage 2
3. **3rd fail**: STOP and notify user
Rollback command:
```bash
$PYTHON_EXE "${CLAUDE_SKILL_DIR}/core/state.py" "$PROJECT_DIR" --reset codegen
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |