Case-study notation. This skill cites the / / MDV-A1101 reference project as concrete evidence for the rules below. The rules themselves are chip-AGNOSTIC and apply to any IC of the matching
ic_class(seevibe-ic-marketplace/plugins/vibe-ic/programs/ic_class_profile.py). When you adopt this skill on a different IC, swap<chip-class>→<your IC name>and<half-duplex-tester>→<your host-tester name>; the structural gates and rule bodies do not depend on those SKUs. Seedocs/design/CASE_STUDIES/AS3616_*.mdfor the full regression history.
Closed Hardware Debug Loop
Phase 2c, post-burn: the plugin's structural gates have all PASSed,
the project's BFM is 12/12 byte-exact, the SOF is burned, but the host
acceptance test (the project's <host_tester> verdict — e.g. byte[6]
on a half-duplex protocol IC, or the equivalent rig verdict for the
target IC class) FAILs. This skill is the methodology that drives the
fix without an indefinite trial-and-error loop.
Why This Skill Exists
After v0.119.5–v0.119.11 the plugin captures Categories A and most of C. Two classes of failure remain:
Category B — vendor doc disagrees with silicon (e.g. v099 oracle returns 18 bytes for 0xE6 but the doc says 22). Plugin extractor cannot detect this from L1-L27 alone. Silicon is measured evidence of the discrepancy; required behavior still comes from the specification or an explicitly accepted input amendment.
Category C residual — sub-microsecond pad / FPGA-pad-inference details that surface only when a particular agent's RTL pattern interacts with a particular silicon's analog front-end. Each new instance becomes a new structural gate (LL-15/16/17/23 are these), but the next one is unknown until it appears.
The closed debug loop converts an indefinite "try-and-error until it works" into a bounded sequence of named experiments, each producing a named evidence file, each leading to a deterministic next step.
When to Use
Trigger when ALL of:
- Selected native tool results in
reports/flow_engine.jsonmeet their original limits and have been AI reviewed; unmeasured work is disclosed asNOT_MEASURED. - BFM
eda_simulateshowsverdict: PASS opcodes=N fails=0. - SOF burned successfully, FPGA JTAG verifies the device.
- Host acceptance test (e.g.
device_tester_md905_connect_test) returnsverdict: FAILwith a non-canonical byte[6].
Do NOT trigger if:
- A selected native tool result FAILs — fix the responsible design or tool behavior first.
- BFM is not yet at 12/12 — fix the byte-level model first.
When NOT to Use
- First fresh-agent run: gates may be FAILing for A/C reasons that must be fixed first; running this skill is wasteful.
- User has not granted oracle reference: Category B requires comparing against a known-PASS SOF or oracle bytewise dump. Stop and ask the user.
Inputs
- A burned, FAILing chip SOF (verified against the project's
<host_tester>rig — seedocs/design/CASE_STUDIES/for + byte[6] reference setup). - A known-PASS oracle SOF (or
eda_oracle_bytewise_dumpcapture). - A scope reachable via
device_scope_capture(Keysight DSO-X class — confirm witheda_device_list category=scope).
Process — 7-Step Closed Loop
Step 1 — Establish baseline FAIL with structured evidence
Run the host acceptance test, capture the verdict + frame bytes:
mcp__eda-tools__device_tester_md905_connect_test collect_seconds=8
Save the response under evidence/baseline_fail.json. Record:
verdict- byte[0..6] of every E0 frame
connect_reply_hexbyte[12..63]
Also record git rev-parse HEAD of vibe-ic-marketplace and
stat -c '%y' of the burned SOF. Reproducibility matters for B
findings.
Step 2 — Burn the oracle and confirm PASS on the rig
This rules out rig drift. Without a confirmed PASS oracle you cannot distinguish "test broken" from "RTL broken".
mcp__eda-tools__eda_fpga_program tool=quartus sof_file=<oracle.sof>
mcp__eda-tools__device_tester_md905_connect_test
Save under evidence/oracle_pass.json. If the oracle does NOT PASS
on the rig, stop — rig is in unknown state, escalate.
Step 3 — Scope-capture both versions
While connect_test runs, capture a 10 ms scope window on the
chip-side bus pin (channel 1 unless project's QSF says otherwise).
Decode pulses by width into BIT0/BIT1/BR/WAKE classes.
mcp__eda-tools__device_scope_capture span_ms=10 trigger_slope=falling
Save evidence/scope_oracle.csv and evidence/scope_chip.csv. Diff
the pulse-train summary:
- same WAKE width (within ±0.5 us tolerance)?
- same WAKE interval (within ±50 us)?
- any data-byte activity beyond the wake pulses?
Step 4 — Decide A vs B vs C with the decision tree
Scope-pulse-trains identical (within tolerance)?
├── YES → Category C: pad-level / fan-out / inference difference.
│ Inspect Quartus *.fit.rpt for the bus pin:
│ - "Combinational Fan-Out" — must be 1 (LL-23)
│ - "Output Enable Source" — should be a pin-local "*~N (inverted)"
│ Bisect by controlled wrapper-flip:
│ take the oracle RTL, swap ONLY the wrapper expression style
│ to your chip's style, recompile, test. The swap that flips
│ PASS→FAIL is the C root cause. Add a structural gate (see
│ the LL-23 template) and commit.
│
└── NO → Category B: a byte stream mismatch.
Run eda_oracle_bytewise_dump on the oracle SOF:
mcp__eda-tools__eda_oracle_bytewise_dump
Save under input/oracle/<name>_bytewise_dump.json.
Diff vs L3.command_table.fields_tx for every opcode the
rig exercises. For each delta:
- record the spec/silicon conflict; patch L3 only after an
explicitly accepted specification amendment
- record in waivers.json["oracle_referenced_fix"]:
{"opcode": "0xE6", "field": "tx_len",
"spec": 22, "silicon": 18,
"evidence": "input/oracle/...bytewise_dump.json"}
- re-run spec-to-rtl
- back to Step 1.
If the scope shows your chip drives NOTHING (only wake pulses) where
the oracle drives a 17-byte response, the chip is not entering the
expected response path. Inspect the chip's main FSM with a
dbg_state_o LED tap; the chip is probably stuck in S_IDLE or
S_RX waiting for a frame_end that never fires.
Step 5 — Apply the fix and run the gate that catches it
Each fix has a corresponding plugin gate (or needs one created):
| Symptom | Likely fix | Gate that catches it post-fix |
|---|---|---|
| TX_IBT < 0.5×tSRS_min | bump IBT to MAX of L2 ibt_us range | LL-15 |
id_bus_oe = a | b in top wrapper |
route everything through tx_phy | LL-16 |
oe ? 0 : 1'bz wrapper |
split into (oe && !tx) ? 0 : 1'bz |
LL-17 |
| Pad fan-out > 1 | reduce internal taps on bus_oe | LL-23 |
| 0xE6 length 22→18 | record conflict; amend L3.fields_tx only after specification acceptance, with evidence | LL-22 |
| Symbolic VID / SN in fields_tx | resolve to OTP byte addresses in L11 | LL-19 |
If the symptom is new, write a structural gate for it BEFORE declaring the fix complete. The gate is the regression guard.
Step 6 — Re-burn, re-test, capture proof
mcp__eda-tools__eda_fpga_compile ...
mcp__eda-tools__eda_fpga_program ...
mcp__eda-tools__device_tester_md905_send_raw cmd_byte=255 # disconnect
mcp__eda-tools__device_tester_md905_connect_test
Save evidence/iter_<N>_pass.json if verdict: PASS. Record the
verdict, the frame bytes, the SOF sha256.
Step 7 — Convergence audit
After byte[6]=0xF2 PASS:
Run the requested hardware acceptance test against the actual device and original requirements. Read the captured waveform, transaction or measurement result; a test name or report presence does not establish success.
This gate verifies:
evidence/baseline_fail.jsonis committed.evidence/iter_N_pass.jsonexists with byte[6] == 0xF2 andtotal_frames >= 5.- Every
oracle_referenced_fixwaiver has a corresponding artifact underinput/oracle/.
Read the actual host acceptance frames and scope evidence against the original
requirements, then AI review each selected native result in
reports/flow_engine.json. Identify rows by current position and name from
flow/steps.json. A Category-B reference explains only the measured hardware
discrepancy; it cannot convert deferred or unmeasured work into PASS. The
hardware result establishes only its exercised scope, not completion of all
Phase 2+3 obligations. Missing native evidence is NOT_MEASURED.
Output Files
| File | Content |
|---|---|
evidence/baseline_fail.json |
First FAIL frames + SOF sha + git rev |
evidence/oracle_pass.json |
Oracle SOF PASS verification on this rig |
evidence/scope_oracle.csv |
Bus pulse train under oracle SOF |
evidence/scope_chip.csv |
Bus pulse train under chip SOF |
input/oracle/<name>_bytewise_dump.json |
Oracle byte stream (Category B) |
evidence/iter_<N>_pass.json |
Final PASS verification |
waivers.json oracle_referenced_fix |
Each B-class spec → silicon delta |
Anti-patterns This Skill Prevents
"Just try a few more things" — the loop is bounded: each iteration produces named evidence and a named decision. If the same gate keeps FAILing across iterations, the methodology has been broken; stop and re-read.
Silently copying oracle bytes — every spec → silicon delta must land in
waivers.jsonwith a link to the dump file. The waiver records the discrepancy and measurement; it is not itself authority to correct the spec. An accepted input amendment must state the changed requirement before the next author follows that delta.Adding fixes without verifying the behavior — reproduce each C-class defect with an input-derived executable challenge, fix its cause in the design, local tool fork or existing producer, and rerun the actual native simulation or hardware test. A relevant behavioral regression can retain that proof without adding a permanent policy checker.
Declaring PASS without re-running the affected native tool — after every fix, rerun the actual simulation or hardware test and compare its report with the unchanged original requirement. AI review that result and affected rows in
reports/flow_engine.json; disclose anything leftNOT_MEASURED.
Native evidence review
After every Step-6 PASS, perform the Step-7 hardware evidence review. Keep the
actual tester frames, scope capture and SOF identity available. Review every
selected tool result against its original limit through the existing
reports/flow_engine.json; no aggregate or format-policy result substitutes
for an unexecuted native tool. A missing value or original limit remains
NOT_MEASURED.
Handoff
- After PASS: hand off to Phase 3 (silicon flow: synth → STA → DFT → PnR → DRC → LVS → GDS → tapeout). The validated chip RTL + waivers form the Phase-3 input.
- After FAIL with bounded retries exhausted: stop and report honestly. The silicon disagrees with the spec in ways the plugin cannot detect from the input alone. Report the conflict and its measurement; change required behavior only through an accepted input amendment, not by copying a known-good SOF.