Skip to content

bjwanneng/veriflow-cc / src/claude_skills/vf-rtl

vf-rtl

Verified

FileKindSize
SELF_IMPROVE.mdmarkdown3.8 KB
SKILL.mdskill md11.2 KB
SKILL_INDEX.mdmarkdown5.5 KB
analysis/bug_pattern_match.pyscript26.9 KB
analysis/corner_case_generator.pyscript4.9 KB
analysis/coverage_analyzer.pyscript5.3 KB
analysis/design_graph.pyscript8.9 KB
analysis/expected_trace_gen.pyscript12.5 KB
analysis/timing_contract_checker.pyscript25.4 KB
analysis/timing_diagnostic.pyscript21.1 KB
analysis/vcd2table.pyscript31.3 KB
bug_patterns.mdmarkdown23.2 KB
coding_style.mdmarkdown9.4 KB
core/init.pyscript13.8 KB
core/rtl_utils.pyscript7.5 KB
core/state.pyscript38.9 KB
design_rules.mdmarkdown2.9 KB
error_recovery.mdmarkdown7.0 KB
kb/knowledge_base.pyscript11.7 KB
kb/reference_kb.pyscript5.6 KB
kb/self_improve.pyscript24.4 KB
references/arbiter_round_robin.vother1.4 KB
references/counter.vother545 B
references/fifo.vother1.3 KB
references/fsm_moore.vother847 B
references/handshake_valid_ready.vother1.1 KB
references/pipeline_aligner.vother760 B
runners/benchmark_runner.pyscript23.6 KB
runners/cocotb_runner.pyscript26.3 KB
runners/iverilog_runner.pyscript26.3 KB
runners/yosys_equiv.pyscript14.2 KB
stage1_spec_golden.mdmarkdown6.1 KB
stage2_codegen.mdmarkdown5.9 KB
stage3_verify_fix.mdmarkdown17.0 KB
stage4_lint_synth.mdmarkdown6.3 KB
templates/cocotb_template.pyscript42.4 KB
templates/golden_model_template.pyscript8.7 KB
templates/spec_template.jsonconfig8.5 KB
templates/tb_integration_template.vother12.4 KB
verify/candidate_selector.pyscript7.0 KB
verify/formal_prove.pyscript12.1 KB
verify/synth_score.pyscript4.4 KB

error_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
```
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: 198kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall