Review RTL
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.
Read the selected rows in <project>/reports/flow_engine.json and open their
native reports. flow/steps.json names each current tool and
flow/native_limits.json retains its original limits. Review tool_ran,
native_steps, native_metrics, and each metric's value, operator and limit.
A missing native measurement is NOT_MEASURED. AI reviews the engineering
meaning of every result and fixes problems in the design, tool or plugin.
python3 programs/flow_engine.py report --project <project>
Run the normal selected RTL validation window first. Read the native Verilator
or Yosys diagnostics and the existing rtl_hygiene_lint.py findings. Preserve
the actual top, source files, include paths, defines and parameters.
Review synthesis hazards, resets and clock domains, style that changes semantics, arithmetic widths and signedness, control correctness, and port fidelity against the input. Inspect the design's encoding, CRC/bit order and counter behavior when the source specification requires those features.
Report each finding with its source location, native evidence where available, and the requirement it violates. Distinguish a confirmed defect from a hypothesis. For a semantic rejection, write a prompt-derived executable test before repair. Rerun the appropriate native lint, simulation or formal tool on the fix. Preserve ECO spare cells and their keep attributes.
A numerical review score, identity receipt or signature is not a tool result. Do not add one to decide whether RTL passes.
Error-flag site classification — recoverable vs fatal (#468)
Review every error-flag assignment site (an error <= 1, err_o = 1'b1,
status[ERR] <= 1, etc. raised on an undefined-access / illegal-command /
out-of-range path). RTL structure alone does not establish whether that error
is recoverable (the FSM keeps serving subsequent transactions) or fatal (the FSM halts / needs reset
to clear). That halt-vs-continue semantic lives in the protocol prose of L3
(external interface / transaction protocol) and L5 (ADI / error-handling spec), not
in the netlist topology — so it is the residual LLM judgment for this skill.
Procedure (per error-flag assignment site):
Read the L3/L5 sentences that describe what the protocol does after this error condition is signalled.
Classify:
- recoverable — the error flag is set on the undefined-access (or
illegal-command / out-of-range) path AND the FSM continues serving the next
transaction per L3/L5 (e.g. "an unsupported command sets the error bit and
the slave returns to IDLE ready for the next frame"). Add the annotation
// fsm_error: recoverableat the assignment site. - fatal — the error flag binds to a halt / lockup state, or L3/L5 says it requires a reset (or explicit clear sequence) to clear before any further transaction is served. Verify the halt/reset behavior and document the requirement.
- recoverable — the error flag is set on the undefined-access (or
illegal-command / out-of-range) path AND the FSM continues serving the next
transaction per L3/L5 (e.g. "an unsupported command sets the error bit and
the slave returns to IDLE ready for the next frame"). Add the annotation
In the review prose, quote the exact L3/L5 sentence(s) that justify the classification.
Derive an executable challenge from the provided prompt and L3/L5: trigger the error, then offer the next legal transaction. Check specified recovery or persistent halt until the required reset/clear. Review the actual native simulation or formal result against that requirement. Missing native evidence is
NOT_MEASURED; hygiene lint does not prove this semantic behavior.
FORBIDDEN: dismissing an error-recovery or fatal-state concern without quoting the L3/L5 sentence(s) that establish recoverable-vs-fatal. An unquoted "this is fine, it's recoverable" is an honesty-rule violation — the annotation must be backed by protocol text, not by an unsupported assertion.
why_not_bucket_a (cannot be a deterministic rule): the halt-vs-continue
judgment requires reading the protocol's error-handling semantics in L3/L5 prose; whether the FSM resumes or
locks up is a property of the spec's intent, not of the RTL's case/state
structure (the same error <= 1 line is recoverable in one protocol and fatal in
another). No regex over the RTL can decide it; it needs the L3/L5 sentence.
Why this is GENERAL: every command/transaction-driven protocol with an error-flag has an undefined-access path; recoverable-vs-fatal is a universal axis of error-handling specs. It names no chip and depends only on generic L3/L5 protocol prose + the gate's structural flag.
Review reset intent
A constant-arm data mux is a possible reset implementation, not proof of an architectural reset. Read the source reset requirement and the actual RTL branch/selector before interpreting a native CDC/RDC finding. Distinguish synchronous reset, functional update and unresolved intent. A signal name, constant value or absent document alone does not establish reset intent.
Verify the source-required behavior with native simulation or formal results. Keep conflicting or insufficient intent unresolved, and never fabricate a source requirement or change rule severity to clear a finding.
Skill: port-name authority comes from the supplied interface contract
Pattern: Named port connections require exact spelling, direction, and width. Derive them from the interface header and any public integration/testbench contract explicitly supplied as design input. A hidden checker is not an input or a source of replacement names.
When to apply: Reset signals named with _n suffix; "shifter" output named q (sometimes scalar, sometimes vector across benchmark conventions); RAM port-direction (input vs inout); parameter casing.
What to do: The supplied interface header WINS over a prose paraphrase: preserve its names, directions, widths, and parameter casing. Check every public instantiation supplied as input for consistency with that header. For a real conflict, use declared source precedence, record the conflict and chosen interpretation, and EMIT RTL; do not ask a human or invent aliases to fit unavailable checker bindings.
Worked pattern (anonymized): a prose summary says scalar output while the supplied normative module header declares a vector. Preserve the header's vector width and check the public instantiation against it.
Why this is GENERAL: Interface compatibility is a design-input contract, independent of any hidden test's binding choices.
Captured by benchmark-enhancement-capture 2026-05-28.
Skill: fix a "mixing blocking and non-blocking" lint warning IN PLACE (=→<=), never by hoisting the assignment into always_comb
Pattern: When a lint review flags blocking-and-non-blocking assignments mixed inside a sequential always_ff/always @(posedge), the correct fix converts the blocking = to non-blocking <= IN PLACE, keeping the signal a REGISTER. Hoisting the computation into a new always_comb instead silences the warning but DELETES a pipeline register — it changes the cycle-accurate latency a functional/reference-model testbench verifies, so the output appears one cycle early and the design fails functionally even though lint now passes.
When to apply: any lint-cleanup task whose flagged signal is reset-initialized / clearly registered inside a clocked block and feeds a pipeline whose latency the harness checks. The tell is the lint gate passing while a functional/sanity test regresses after the "fix".
What to do: keep the signal in its clocked block and swap = for <= so it stays a register and preserves its +1 pipeline cycle. Do NOT relocate a registered computation to always_comb to resolve the warning.
Why this is GENERAL: choosing a lint fix that preserves the design's cycle behaviour (rather than the first edit that silences the warning) is universal — deleting a register to quiet a linter is a real latency regression. why_not_bucket_a: the linter flags the mixing but cannot choose between two functionally-DIFFERENT remedies; deciding to keep the signal registered (because it is a latency-bearing pipeline stage the reference model samples) over hoisting it combinational requires understanding the signal's timing role, a reading judgment the lint message does not carry.
Captured by benchmark-enhancement-capture 2026-06-30.
Skill: carry a single-cycle event across clock domains as a HELD level, not a 1-cycle pulse
Pattern: A one-cycle pulse pushed through a 2-FF synchronizer can fall ENTIRELY between the receiving domain's edges (lost), and re-narrowing it back to a 1-cycle pulse on the far side fails a consumer that samples a LEVEL at a fixed instant. Convert the event to a held level (or a toggle whose level is synchronized) so the receiver always captures it regardless of the clock-frequency ratio.
When to apply: Any single-cycle event (ack/req/done) crossing from one clock domain to another where the consumer samples a level. Unless both domains share a clock or the protocol explicitly uses a synchronized toggle/handshake.
What to do: Drive a HELD level on the event, synchronize that level across the domain (2-FF), and clear/re-arm only when the originating request is withdrawn; do NOT edge-detect the crossing back into a 1-cycle pulse if the consumer reads a level.
Why this is GENERAL: level/toggle synchronization for single-cycle events is textbook CDC. why_not_bucket_a: recognizing that the consumer samples a level (so a pulse must become a held level across the crossing) requires reading the receiving-domain sampling semantics, not a regex.
Skill: a multi-clock bridge clocks each side's logic on the clock the spec BINDS to that side — cross-domain signals need synchronization
Pattern: When a spec names TWO (or more) clocks and binds each one to a specific protocol side or sub-block — e.g. "clock A: clock for the operations", "clock B: clock for the operations", often paired with a per-side reset — the registers of each side must be clocked by ITS named clock, and a control/data signal that travels from one named-clock domain into the other must cross with proper synchronization (and, per any "hold attributes during the transaction" cue, be held stable across the crossing). The recurring defect clocks the whole module on a single clock (usually the first-listed one), which mis-times the other side's phase/handshake and breaks any checker that advances that side on its own clock edge.
When to apply: any bridge / adapter / dual-port / CDC design whose prompt enumerates more than one clock input and verbally assigns each clock to a side, sub-block, or interface. The tell is logic that functions when both clocks happen to be in lockstep but mis-sequences the second interface, or a testbench that drives the two clocks as independent edges.
What to do: partition the RTL into per-clock always blocks, clocking each block on the clock its spec sentence binds to that side (and resetting it with that side's named reset); for a single-cycle event or attribute crossing between the two domains, pass it through a synchronizer / held level rather than letting it be sampled directly on the far clock.
Why this is GENERAL: assigning each block to the clock the spec names for it, and synchronizing the crossings, is baseline multi-clock discipline applicable to any bridge with named per-side clocks. why_not_bucket_a: a program can count clock inputs but cannot decide WHICH logic belongs to WHICH clock — the binding lives only in the prose description of each clock ("this clock is for that side"), so partitioning the design across the named clocks requires reading and matching those sentences, a semantic judgment, not a structural rule.