RTL Repair
Register value convention
Read flow/rtl_conventions.json#register_initial_value from this plugin tree
before writing, repairing or reviewing RTL. A value stated in the original input
wins. If the input is silent, use a recognized circuit-class convention from
the table when one applies; otherwise use zero, including internal state. Use a
reset assignment when the register has a reset, otherwise an initial assignment. A reset is the startup mechanism unless the input explicitly requires a
separate initial value. Mark defaults and conventions visibly in RTL comments and list
register, value, mechanism and convention/source in the report. On chip and IP routes, initial-only
storage is a reported, nonblocking finding. This table defines the input/convention/zero
precedence. Never derive values from a testbench, scorer, reference
answer or score. The scorer must not modify candidates.
Close the Generate-Compile-Feedback-Repair loop for RTL. Takes a broken module plus a log (lint, synthesis, or simulation) and produces a corrected module, with a diff and a reasoning trace.
When to use
Trigger when the user:
- Shares RTL plus error output from a lint tool (SpyGlass, Verilator, Icarus)
- Reports a synthesis error from Yosys, DC, or Genus
- Reports a simulation mismatch where golden and DUT differ
- Asks to "auto-fix" the issues surfaced by
/rtl-review
Inputs to gather
- The RTL file(s)
- The error log or failing-test output
- Intent: "minimal fix" (patch only the error) vs "refactor for cleanliness"
- Whether to preserve original comments and signal names
Repair workflow
- Parse the error log — group issues by root cause, not by line count. One fix often resolves many lints.
- Rank by severity — synthesis-blocking errors first, then warnings, then style issues.
- Plan the patch — for each root cause, describe the fix in one sentence before touching the code.
- Apply minimal edits — prefer surgical diffs over rewrites unless the user asked for a refactor.
- Re-check mentally — walk the new code through the failing case and confirm the fix is valid.
- Emit diff + explanation — show what changed and why.
Output format
Produce:
# RTL Repair — <filename>
## Root causes identified
1. <root cause 1> → <line range> → <fix strategy>
2. ...
## Patch
```diff
- <old line>
+ <new line>
Why each change works
- <change 1>:
Remaining risks
- <anything the repair couldn't address without more info>
Next step
Re-run /rtl-review to confirm clean, then /testbench-gen or existing tests.
## Technical basis
Implements the iterative repair loop from AutoChip, RTLFixer, and VerilogCoder. Empirical result: iterative compile-feedback-repair lifts functional correctness of LLM-generated RTL by 20–40% over single-shot generation.
## Declared in-order transaction watchdog (Program First)
A single-flight timer that clears on any completion is not a multi-outstanding
watchdog. The reusable mechanism is enforced by
`programs/in_order_watchdog_synth.py`, consumed by the existing
`canonical_primitive_synth.py` project front door and the normal RTL runner's
canonical-primitive path. It emits a new candidate only; it never replaces an
existing design or marks it functionally accepted.
Before emission, map the PUBLIC input to `input/in_order_watchdog.json`.
Mapping the prose's policy choices is explicit AI/owner work, not a regex guess.
Use schema `vibeic.in_order_watchdog.v1` and declare all of:
- `module` and distinct `ports` roles: `clock`, `reset`, `request_valid`,
`request_ready`, `response_done`, `threshold`, `timed_out`, `violation`.
- `counter_bits` (1..64), `max_accepted` (1..1024), and `response_order:
"in_order"`. Capacity is that bound plus ONE stalled slot only for
`start: "first_valid"`; `start: "accepted"` measures accepted requests only.
Declare `request_protocol: "hold_valid_until_accepted"`; cancellation is
unsupported. Withdrawing a stalled VALID or accepting above the bound also
asserts the runtime contract violation rather than silently losing a timer.
- `reset: {"polarity": "high"|"low", "synchrony": "sync"|"async"}` and
`flag: "sticky_until_reset"|"pulse"`. Never clear a prompt-sticky flag on
completion or idle. Other clear policies are unsupported, not defaulted.
- `initial_age: 0`, `timeout_compare: "next_age_ge"`, `saturation: "max"`,
`zero_latency: "complete_on_accept"`, and `violation_policy:
"sticky_until_reset"`. Age zero is stored on the start edge; existing
next-age >= runtime threshold is compared on each subsequent sampling edge.
Threshold zero also trips a new entry. A same-edge accepted completion with
no older work creates no unfinished entry. Retiring the oldest does not
suppress comparisons for other transactions.
- `mapping: {"actor": "AI"|"owner", "source": "input/<public>.md",
"sha256": "<source digest>", "citations": {...}}`. Supply a nonempty exact
source quote for EACH field above (including `module`, `ports`, `reset` and
all policy fields; exclude `schema` and `mapping`). Hash and quote checking
binds the source; it does NOT prove the mapping entails the policy. Retain
the mapping for independent AI review and normal Program gates.
Invoke the ACTUAL shared consumer, not an unused utility:
```bash
python3 ${CLAUDE_PLUGIN_ROOT}/programs/canonical_primitive_synth.py <project> --emit
EMIT is generation, not PASS of the repaired design. Existing RTL is never
clobbered: the normal runner defers to authored/supplied RTL, and this explicit
CLI refuses an occupied output. Missing declaration leaves ordinary canonical
detection unchanged; incomplete/changed source, malformed parameters, unknown
policy or out-of-order retirement emits WATCHDOG_CONTRACT_REFUSED and writes
no candidate. Runtime capacity overflow or orphan completion asserts the
declared sticky violation output; the integrator must treat it as a contract
failure, not waive it or silently drop outstanding work.
Verify at least: first completion with a second request still unfinished; held VALID versus consecutive accepts; simultaneous pop/push; threshold 0/1 and runtime changes; saturation; reset polarity/synchrony and sticky/pulse policy. Re-run the original independent challenge, normal gates and fresh review before claiming repair acceptance. A prepared product capture is not closed while those checks or publication are pending.
Source-bound structural-only repair evidence
When an explicit implementation structure is part of the public input but the
candidate is functionally equivalent, do not manufacture a simulation failure.
Use the existing normal repair contract consumer with a
vibeic.native_structural_contract.v1 declaration. It binds the unique public
requirement quote, original and candidate source hashes, top, immutable native
tool image, and typed cell expectations. The consumer replays the fixed
read_verilog; hierarchy; proc; opt; write_json proof at
RTLIL_AFTER_PROC_OPT; authors cannot inject a synthesis mapping or command.
An absent structural declaration means the design is unconstrained and must not
fail for choosing an equivalent architecture. A present declaration with an
ambiguous requirement, abstraction, top, or scope is NOT_MEASURED and cannot
authorize repair. A structural repair must still pass the ordinary functional
challenge and Program gates, then replay the same hash-bound structural proof;
structural evidence never substitutes for functional evidence.
Do not
- Do not silently change module interfaces — if a port must change, flag it explicitly
- Do not delete code to make errors go away; fix the root cause
- Do not repair if the root cause is ambiguous; ask the user instead
Modify-task file delivery — extend, don't replace (issue #139 class)
When the repair/modification deliverable is one of the PROVIDED files and your change adds a NEW module that instantiates the provided one, the delivered file must contain BOTH: the original module (verbatim except the requested edits) AND the new logic. Overwriting the file with only the new module deletes the definition the new logic depends on — the design stops elaborating (unknown module) and every pre-existing consumer breaks. "Extend" means the given design plus your addition; deleting provided logic requires an explicit instruction to replace it.
Deterministic backstop (run before delivering):
python3 plugins/vibe-ic/programs/file_extend_preserve_check.py \
--before <original_files_dir> --after <delivered_files_dir>
Exit 1 = self-breaking clobber (an overwritten definition the delivered set still instantiates) — restore the original module alongside the new one.
why_not_bucket_a: whether dropping a provided module that NOTHING still
instantiates was an INTENDED replacement is task-wording judgment — that half
stays advisory (IC Expert DB class functional-modification-delivery); the
program flags only the zero-false-positive self-breaking sub-case.
⛔ ECO spare-cell preservation (mandatory)
Compare the native netlist or implementation database before and after optimization. Preserve every unused ECO spare, its keep attributes and the reserved pads; an unintentionally removed spare must be restored.
Before repairing a receive or packet FSM, separate three events: accepting the last payload item, updating the payload registers, and exposing the completion flag. Derive their relative edges and settled intervals from the current public specification; the payload length alone does not determine completion latency.
Keep source rows on both sides of each relevant edge in the regression test. Check settled flag/data values as well as edge-triggered state changes, so an active-region/nonblocking-assignment race cannot explain away a genuine early completion. Preserve the original failing challenge and check consecutive transactions, payload retention during completion, and the stated reset mode. If the source supplies only simultaneous input/clock transitions without a sampling rule, retain that ambiguity instead of inventing a universal delay.
Smallest fix of the original problem (Charter C10, owner 2026-11-14)
Owner: "fixing PR/issue 不要越搞越複雜,用最小的方式、最小的改動去修正原來的問題." Before a fix, state the original problem in one sentence; keep main's existing path and change only what that problem needs. Review asks only: is the original problem fixed, is anything worse than main, and is the fix general and no-cheating? A defect found in behaviour main already has is a separate known gap, written down, never folded into the same PR. After about two SEND BACKs, or when a PR keeps adding new mechanism (parsers, analyses, inventories, readers) to answer counterexamples, stop and restart from main as the smallest fix of the original problem. A smallest fix enters the plugin or a skill only if it is also general and no-cheating (owner 2026-11-14): it holds for any design meeting the same condition, names no benchmark, problem, design or testbench, and takes nothing from a testbench, reference answer, scorer or score. A design-specific fix belongs in that design, not in the product.