spec-to-rtl — the runner-orchestrated AI authoring step
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.
What this skill IS
The deterministic authoring path for IC classes WITHOUT a registered rtl_gen
generator. Spec → RTL fundamentally requires a language model (open-benchmark-
methodology skill § 1); this skill is how the runner delegates that step to
the AI inside its own pipeline, so the surrounding gates still fire.
Invocation contract
Skill: Functional RTL before production scan insertion
When the design declares production scan in L20, complete the functional RTL
authoring handoff before the native DFT steps. If the deterministic producers
decline, invoke this skill and write the functional RTL at the requested path.
The staged fallback is an authoring request; rerunning an empty RTL directory
does not complete it. Record AI authorship in the existing
phase2/stage1/ai_backup_author.json and reenter the normal public runner.
Preserve the functional interface, reset behavior and timing from the design input. Native DFT insertion owns scan-cell replacement, stitching and the added test ports specified by L20. Determine chain length from the implemented design. Review the native scan replay and subsequent functional replay separately. Functional simulation alone does not establish scan or ATPG acceptance.
For an existing AI_BACKUP task carrying spec_clarification, read the complete
original input and its two source-bound observable readings. Choose one
source-compatible reading for each request and actually author the RTL in
write_rtl_to. Record selected_readings as one integer 0 or 1 per request,
with source quotes, rationale and the named AI author in the normal completion
record. Do not relabel preserved Program RTL as AI work. Fresh authoring may
produce identical bytes. The coordinator preserves the original Program result,
candidate, review and tests; it retires only its mutable RTL workcopy. Reenter
the existing native gates and fresh independent review before acceptance. The
choice does not waive failed challenges, rewrite source, or earn Program credit.
Do not requeue the same ambiguity after that choice has been completed.
When design_one_shot_runner.step_rtl_gen WAIVES with the message:
IC class 'XXX' registered but rtl_gen=null. Recommended action: AI invokes skill
spec-to-rtl.
…the AI MUST:
Read the input contract named by the runner handoff. For the explicit bounded D09 position 17
input_authority=originalcontract, read the entireread_prompt_fromfile and everyread_context_fromfile. Verify their recorded SHA-256 values before authoring or reviewing. These are the authoritative source bytes; do not substitute generated Ldocs or require a D01 position 1 document review for this RTL-only request. A changed or missing source requires returning to the ordinary runner, not silently adopting it. This handoff asserts neither D01 position 1 PASS nor measured RTL behavior.For the default structured contract, read the L docs the runner emitted:
<project>/phase1/generated_docs/L1_*.json(product metadata, IC name, target clock)<project>/phase1/generated_docs/L2_*.json(functional spec)<project>/phase1/generated_docs/L3_*.json(external interface — ports)<project>/phase1/generated_docs/L7_*.json(verification plan / truth-tables)<project>/phase1/generated_docs/L9_*.json(constraints, top_module name, top_ports)- For Path-A (NL prompt) projects, ALSO read the original prompt at
<project>/input/phase1_prompt.mdor<project>/input/docs/*.md. The prompt typically has clearer port-name and behavioral details than the auto-extracted L docs. - When the handoff supplies verified
public_original_input_paths, ALSO read those original RTL and context files. Preserve their exact interface and supplied behavior while applying the prompt's requested completion or change; use the same authoring method below with these source inputs.
— and CONSULT THE CAPTURED-LESSON DIGEST (MANDATORY) — The runner's WAIVE step deterministically writes
<project>/phase2/stage1/lessons.md(and setslessons_digest+lessons_countin its handoffextras): a chip-AGNOSTIC digest of every### Skill:genre/topology convention captured from prior recoveries. BEFORE you author, OPEN it, keyword-match THIS design's genre against each section's**When to apply**line, and APPLY every match. These are general advisory patterns (frequency/clock-divider dual-edge-OR LEVEL topology, shifter logical-vs-rotate default, FIFO Gray-pointer, restoring-divider remainder width, overlapping-sequence FSM re-seed, valid/ready handshake inference, …), not per-problem answers. Use a matched technique only when it is consistent with the complete current input. Record choices the source leaves free; a prior checker or benchmark result cannot supply missing intent.— and LIST THE OTHER ARTIFACTS THE SPEC MAKES MANDATORY (MANDATORY) — The WAIVE handoff tells you two things: write the RTL here, and read
lessons.md. It says nothing about the OTHER artifacts the same spec makes mandatory and that you are the only one who can produce. Those clauses are already extractable from the SAME input docs you have just read, so run the preflight BEFORE you author:python3 plugins/vibe-ic/programs/spec_required_artifact_check.py \ <project> --preflightIt prints every still-OUTSTANDING spec-declared artifact with the input doc and the clause that demands it, and always exits 0 — at handoff those files are legitimately absent, so it can never block a correct run. Author each one alongside the RTL. Skipping this does not make the requirement go away: the same extraction runs as a BLOCKING assertion at
final_audit, so a missing declaration costs an entire Phase 2 (hygiene, lint, synth, DFT, a multi-minute LEC) to discover a file that took seconds to write.— and DECIDE + RECORD YOUR FREE CHOICES BEFORE YOU AUTHOR (MANDATORY) — The preflight above tells you WHICH files the spec demands. When one of them is a DECLARATION — a "MUST declare
<path>" clause followed by a field table — the file is not paperwork you can write afterwards. Its fields are FREE CHOICES: decisions no downstream tool can recover by inference (serial bit order, reset-release latency, integer encoding, reset polarity, the parameter this build ran at, which optional feature axis you selected). Two correct designs disagree on all of them, so the comparison procedure cannot pair its reference output unless you tell it.The runner already staged the contract for you at
<project>/phase2/stage1/declaration_contract.json(extras keydeclaration_contract). Read it, DECIDE each field, and record them:python3 plugins/vibe-ic/programs/spec_declaration_emit.py <project> --contract python3 plugins/vibe-ic/programs/spec_declaration_emit.py <project> \ --set <field>=<value> --set <field>=<value> ...Then author RTL that CONFORMS to what you declared — not the other way round.
Rules that are easy to get wrong:
- The emitter refuses (rc=1, naming the field) while any REQUIRED choice is undetermined, and writes nothing. That refusal is correct: a default-filled declaration would turn the required-artifact gate green against a value nobody chose.
- Do not copy the spec's example value into the declaration. The example column records what a reference implementation happened to pick; copying it makes the document author the designer.
- An informational field you did not decide is omitted, never placeholder-filled.
--from-rtl-declarationexists ONLY for a legacy design whose RTL was written before the declaration; it promotes an existingkey = valueheader block and stamps every field it takes asrecovered_from_prosein the provenance sidecar. Do not use it as the normal path — a free choice recorded only in an RTL comment is a free choice a downstream tool has to guess.
Respect the blind rule: read ONLY the L docs, original prompt, and the handoff's verified
public_original_input_pathswhen supplied. NEVER read hidden or unlisted benchmark testbenches, harnesses, or reference RTL (for exampletestbench.vorverified_*.v). This is enforced by the open-benchmark- methodology skill's absolute-blindness rule and applies inside this skill.Determine the module name:
- If
L9_INTEGRATION_SPEC.jsondeclarestop_module(e.g."chip_top") AND that matches the description's stated module name, use that. - Otherwise: use the exact name the prompt/description states ("Module name: ") as its supplied interface contract. The runner's chip_top auto-emit (v0.1.32+) will wrap your module if L9.top_module differs.
- If
Author synthesizable RTL at the runner's expected path:
<project>/phase2/stage1/rtl/<module_name>.v (or .sv)- Verilog-2001 or SystemVerilog; synthesizable for yosys + gf180/sky130
- EXACT port list per L3 / L9: names, directions, widths (
[3:0]⇒ 4 bits) - Implement the behavior the description states. Algorithm choices the description doesn't pin down are R3-permitted design freedom.
Apply known hygiene proactively (so the runner's gates don't have to work around them):
- Combinational
always @(*)blocks: every branch assigns every output OR adefaultcovers them (no inferred latches). - Reset-less registered outputs: when input is silent or ambiguous, add
initial <reg> = 0;in a SEPARATEinitialblock (not inline on an output declaration), matchingrtl_hygiene_lint --fix, and record this DEFAULT as an assumption. Only an explicit contrary initial value overrides it; preserve a supplied nonzero startup value rather than resetting it to zero. case: includedefault; rewrite overlappingcasezpriority encoders asif/else-if.
- Combinational
Run native validation before handoff. Compile the RTL with the actual selected top, source set, include paths, defines and parameters. Use full native simulator code generation and native lint. Run a functional testbench derived only from the prompt's worked examples, tables, boundaries and error behavior. Missing execution remains NOT_MEASURED. Preserve benchmark actor isolation; the author does not read the hidden harness or oracle.
6b. Prompt→interface conformance pre-emit check (ORGANIC #695). Before handing back, run the deterministic interface gate — it reads ONLY the prompt + your RTL (BLIND; never the oracle/hidden TB) and flags the three PROMPT-DERIVABLE interface misses that prevent a supplied caller from binding:
python3 plugins/vibe-ic/programs/iface_conformance_v2.py \
--id <problem_id> \
--prompt <prompt.txt> \
--rtl <project>/phase2/stage1/rtl/<module_name>.v
It checks (1) MODULE-NAME-CASE — the RTL module name must match the
supplied interface header CASE-EXACTLY (stream_unit and StreamUnit
are different names). If the input leaves the name open, use the supplied
file/id stem DEFAULT and record the assumption; only explicit contrary input
overrides it. The interface header wins; check any public instantiation
supplied as input for consistency; (2) MISSING-PORT — every
interface signal the prompt NAMES (table rows, backtick signal names with a
nearby direction, a given-code module header, wavedrom name entries) must
appear in your port list (AXI master must keep ar*/aw*, s_ready, etc.);
(3) PORT-DIRECTION — a port's direction must match the prompt's signal table
(do not declare an output where the supplied interface declares an input).
ADVISORY by default (prompt extraction is heuristic — an internal signal
mentioned in prose is NOT a port and must not block); add --strict to make
any finding exit 1 once you've confirmed the named signals really are ports.
FIX every confirmed finding before emit — these are deterministic
elaboration/bind failures implied by the supplied interface.
6c. Spec-first coverage attribution pre-emit gate (ORGANIC #697).
Enumerate requirements from the complete supplied input chain and exercise
them with independent tests. This local coverage check cannot predict the
coverage or expected behavior of held-back tests. It reads only supplied
inputs, generated L-docs, candidate RTL and the current self-testbench.
python3 plugins/vibe-ic/programs/spec_coverage_check.py \
--prompt <prompt.txt> --ldocs <project>/generated_docs/ \
[--fact-graph <fact_graph.json>] \
--rtl <project>/phase2/stage1/rtl/<module_name>.v \
--tb <your_functional_tb.sv> --strict
It extracts a DETERMINISTIC checklist (ports/widths/directions, reset
value+polarity+sync/async, stated latency, every table row, every worked
example, every ENUMERATED SET + its outside-the-set/default boundary —
the most-missed #697 pattern — signed-ness, byte order, overflow, handshake)
from EVERY chain station and reports any item your TB leaves UNCOVERED
(--strict BLOCKs on a coverage gap). FIX the gap by adding the missing
directed stimulus/assertion (especially an OUTSIDE-the-set value for any
enumerated set). On a downstream FAIL, re-run with --failure "<behavior>":
a coverage-gap ⇒ enhance your TB; an extraction-gap ⇒ the program names
the route_to: station (ic-expert-agent / spec-to-rtl) that
dropped the requirement (community-backlog it); only a cited spec-absent is
a genuine floor. The structural extraction + routing is deterministic;
deciding whether a prose sentence is a distinct testable requirement (so
you can author its stimulus) is your LLM judgment.
7. Return the authored RTL and handoff to the public
vibe_ic_one_shot_runner.py entry using the original project, route, and
Router-selected evidence window. The native runner executes the applicable
validation, CDC, simulation, and formal tools. Read each native result
against its original limit. Missing measurements remain NOT_MEASURED, and
tool failures remain FAIL. Authoring alone does not establish downstream
or whole-chip acceptance. For benchmarks, independent blind AI review and
official scoring remain required.
What this skill IS NOT
- NOT a fully-deterministic program. Spec→Verilog needs an LLM; this skill is the AI's role inside the runner pipeline, with all the structural gates wrapping it.
- NOT a bypass of the runner. Bypass = authoring with MCP outside the
runner's pipeline (no phase1 L doc context, no chip_top auto-emit, no
hygiene
--fix, no rtl_repair_retry, no conformance, no audit). Use this skill for the runner-issued authoring handoff. - NOT a free pass to ignore the blind rule. The original benchmark's testbench / golden RTL are STILL HIDDEN during this authoring step. Only the host scorer (after all gates run) touches them.
Quality bar
A "good" spec-to-rtl emission means:
- Read the native simulation or formal result for the selected source, top and configuration. Do not add a separate harness-identity or source-hash requirement.
eda_synthgf180 emits ≥1 cell (not pure-passthrough; not optimised to nothing).- The module name + port list match the description verbatim.
- No latches inferred (or, if a latch IS intended per the description,
declared
always_latch). - Reset-less registered outputs use a separate initial-zero block by DEFAULT when input is silent or ambiguous; record the assumption. An explicit contrary startup value overrides this default and is preserved.
If you cannot satisfy this from the description blindly (e.g. the description genuinely under-specifies a parameter the TB will instantiate by name), emit your best honest reading and let the runner's downstream gates report the mismatch. Per the open-benchmark-methodology skill § 4 Cat B, that's documented as benchmark under-specification, not a skill failure.
Runner handoff
The runner-issued authoring handoff names this skill and the required output path. Use that handoff to continue inside the normal product flow. An absent skill or input is a product handoff defect, not a benchmark answer or a design verdict.
Error-flag behavior — classify recoverable vs fatal from L3/L5 (#468)
When you author RTL that raises an error flag on an undefined-access /
illegal-command / out-of-range path, decide from the L3/L5 protocol prose
(not from convenience) whether the FSM should recover or halt, and encode
that decision in RTL behavior and document it for /rtl-review:
- recoverable — if L3 (transaction protocol) / L5 (error-handling spec) says the
block sets the error flag and continues serving the next transaction (returns to
IDLE/ready), implement exactly that: raise the flag, then transition back to the
serving state. Add a
// fsm_error: recoverableannotation at the error-assign site so the reviewer can confirm without re-deriving the semantics. - fatal — if L3/L5 binds the error to a halt/lockup state or says it requires a reset (or explicit clear) to clear, implement the halt and do NOT add the recoverable annotation; the FSM stays in the error state until reset.
FORBIDDEN: annotating a site // fsm_error: recoverable (or, in review, dismissing
a behavioral failure) without the L3/L5 sentence(s) that establish the halt-vs-continue
behavior. The annotation is a claim about the spec and must be backed by spec text.
Verify the decision with a prompt-derived executable challenge: trigger the
error, offer the next legal transaction and check either the specified recovery
or the required halt until reset/clear. Read the native simulation or formal
result against the unchanged requirement and AI review it. Missing evidence is
NOT_MEASURED. A hygiene lint result does not prove error recovery or fatality.
why_not_bucket_a: the recoverable-vs-fatal call is a semantic judgment
that lives in protocol prose (L3/L5), not in RTL structure; the identical
error <= 1'b1 line means "keep going" in one protocol and "lock until reset" in
another, so no deterministic rule over the RTL can decide it. This is the residual LLM
authoring judgment, cross-referenced with /rtl-review's matching classification
section.
Output timing — same-cycle (Moore-combinational) vs registered pulse (#560)
For an INPUT-defined same-cycle status / event / strobe, a registered pulse
(out <= <event>; under a clock) can add a cycle that violates that requirement.
A self-authored cocotb check must use the source-defined observation phase;
a testbench's own sampling style cannot decide the required output timing.
Decide the output's timing from the complete supplied INPUT, then encode it: Read prose, diagrams and timing tables together. The forms below are techniques, not a universal keyword rule. If timing remains silent or ambiguous, send it to AI authoring with that ambiguity named.
same-cycle (Moore-combinational decode) — when the spec describes the output and its triggering event in the same breath ("asserts
donewhen the count reaches N", "driveserroron an invalid command", "validis high while in state S") and the complete INPUT fixes that same-cycle relation, derive the output combinationally from state / inputs and do NOT register it:// Moore decode — same-cycle, no register delay assign done = (state == DONE); always @(*) error = (cmd_valid && !cmd_legal);This serves source-defined state decodes and same-cycle event strobes; an unprovided checker cannot make it the default for an ambiguous interface.
registered / next-cycle — ONLY when the prose explicitly says the output is registered, appears one cycle after the event, is pipelined, or must be glitch-free for an external interface. Then use the NBA form:
always @(posedge clk) out <= <event>; // intentional 1-cycle latency
Application examples: an input-defined same-cycle vending-machine
error+return, an output required to track an FSM state, or a source-defined
same-cycle serial-interface event can use a combinational decode. Verify the
specified phase with an input-derived check; previous benchmark FAIL/PASS
outcomes do not establish which phase a new design requires.
why_not_bucket_a: same-cycle vs registered is a reading of the spec prose ("when"/"on"/"while" vs "registered"/"one cycle later"/"pipelined") together with its supplied diagrams and edge relations, not a hidden testbench convention. The identical event→output mapping is correct as combinational in one problem and as registered in another; no regex over the RTL or the prompt reliably separates the two, so this stays an LLM authoring judgment.
Independent differential self-verification
When the RTL and its testbench share one interpretation, both can repeat the same semantic mistake. Derive an independent reference from the actual input, including clock-edge timing, reset values, latency, signedness, bit order, overflow and default/error behavior. Preserve benchmark blindness.
Drive the RTL and reference with the same directed, random and boundary stimuli using the selected native simulator. Compare every required output at the source-defined sampling event. Retain the first mismatching cycle, signal and input sequence. Read the source to decide which implementation is wrong, then add that input-derived case to the regression and rerun. Agreement on a bounded test set does not establish complete correctness.
Latency/timing conformance — the PROGRAM measures, not your self-TB (#705)
When the spec states an EXACT latency — "output asserts N cycles after the start event", "WIDTH+2-cycle delay", "1 cycle overhead when transitioning IDLE→BUSY registering inputs" — DO NOT trust your self-TB's measurement. An expected model derived from the same mistaken edge convention can confirm incorrect RTL. Derive the event, counting edge and observation point independently from the current supplied timing contract.
latency_conformance_check.py measures the selected event and output. Its
one-clock active-high event pulse and positive-edge count are an explicit
measurement convention, not a universal interface contract. Use this mode only
when it implements the supplied event polarity, duration, counting edge and
observation point. If that contract differs, adapt the measurement stimulus to
the input or report the unsupported measurement. Never change RTL to match an
inapplicable measurement convention. A mismatch calls for RTL repair only after
confirming that the measurement implements the input contract.
python3 plugins/vibe-ic/programs/latency_conformance_check.py \
--rtl <your_rtl.sv> --top <module> \
--event <start_port> --output <valid_port> --expect "<expr>"
--expectis the spec latency literal as arithmetic over the module's parameters (WIDTH+2,N+1,8); resolved against the#(...)defaults (or a--param NAME=VALoverride). It is evaluated by a tiny SAFE evaluator (digits, param names,+ - * // ( )only — nevereval).LATENCY-MISMATCH: measured=<m> but spec <expr>=<e>(rc 1) = your RTL's real latency under this measurement is<m>. Confirm its event and edge convention against the input before repairing RTL or correcting the measurement.latency-conformance ok: measured=<m> == spec <expr>(rc 0) = the measured latency matches the spec literal — emit.- iverilog absent → a distinct
SKIP(rc 0), never a fabricated PASS; the output never asserting →LATENCY-TIMEOUT(rc 1).
why_not_bucket_a: the canonical MEASUREMENT (build the TB, pulse the event,
count posedges to the output assertion) + the comparison against the resolved
literal IS the deterministic program. The LLM residual is reading the spec to
decide WHICH port is the event, WHICH is the output, and WHICH
expected expression the prose names (WIDTH+2 vs N+1 vs a constant). This is
the timing complement to #697 (coverage attribution — force the self-TB to
COVER each dimension) and #700 (independent differential verify — cross-check
a second derivation): #705 supplies the absolute latency yard-stick those two do
not.
"Read the simulation waveform" tables — the PROGRAM replays the published table (#716)
When the prompt embeds a literal simulation table — rows of
time [clk] <input...> [internal...] <output> under a "Read the simulation
waveforms to determine what the circuit does, then implement it" instruction
— the table IS a directed test vector you
must reproduce exactly. Count pipeline depth from the first DEFINED output
transition, not from the first x. Early X rows are not an extra register stage:
an input-sampling NBA race (@(posedge) a<=val) can leave the input unknown at the
first edge, and the table's X-match convention consumes that unconstrained window.
Do NOT add a stage just to explain early X. Keep this default on silent or ambiguous
stage-count wording and record the assumption; an explicit contrary latency or
fully defined timing requirement overrides it. Check every defined row. For a real
source conflict, pick by declared precedence, record it, and emit RTL without asking
a human or importing a hidden reference's implementation.
waveform_table_conformance_check.py is the independent yard-stick. It parses the
table and replays it with its implemented X-match (X in the table matches
anything; X in the DUT only matches a table X). Confirm that this comparison
convention matches INPUT; a scorer cannot supply missing X semantics. It
BLOCKS on any mismatch under that convention:
python3 plugins/vibe-ic/programs/waveform_table_conformance_check.py \
--prompt <prompt.txt> --rtl <your_rtl.sv> --top <module>
WTC_PASS(rc 0) — the RTL reproduces the published table; emit.WTC_FAIL mismatches=<n>+ per-rowWTC_MISMATCH t=.. expected=.. got=..(rc 1) — your RTL diverges from the table (the stage-count / inversion / function is wrong). Fix and re-run.WTC_SKIP_<reason>/WTC_NO_TABLE(rc 0) — the prompt has no table, OR the design is outside the proven-faithful envelope (a negedge / level-sensitive transparent latch, a multi-bit/hex output column, a Moore FSM exposing multiple observable outputs, or non-binary table values). The gate refuses to block these — its replay timing is only proven faithful for combinational truth-tables and single-bit single-clock posedge-registered outputs, so for everything else it advises rather than blocks (NO false-block).- iverilog absent →
WTC_SKIP_no_tools(rc 0), never a fabricated PASS.
why_not_bucket_a: parsing the table, building the directed replay TB, running
it under its documented X-match, and comparing every row IS the deterministic
program. The LLM residual is reading the prose to confirm it is a
"read-the-waveform" problem and, on a WTC_FAIL, deciding WHICH clause of the
RTL (stage count, polarity, function) the mismatch implicates. This is the
DIRECTED-VECTOR complement to #700 (a random differential cross-check, which
is circular here because a stage-count misread biases BOTH the RTL and a
hand-derived ref) and #705 (which needs a prose latency literal a
waveform-only prompt does not supply).
Behavioral-prose Moore FSM — extract the table, let the PROGRAM emit (2026-06-23)
Most FSMs whose states + transitions are stated in NARRATIVE PROSE (Lemmings with
dig/splat/counter precedence; a PS/2 byte-boundary search; a sliding-window counter;
a multi-phase controller) still need a language model to read prose into structure.
One strict basic carve-out is already program-solved: when a directional bump+fall
walker explicitly states both direction mappings, both-side behavior, fall/resume
memory, all three bump/fall boundary priorities, Moore outputs, reset, and clock
edge, behavioral_fsm_synth.py parses those facts into a complete four-state table
and the registry emits it. Missing any fact or adding dig/splat/timer behavior is a
safe SKIP. For every remaining narrative shape, once the AI extracts a COMPLETE
enumerated table, emitting correct RTL is a pure formula. So DO NOT hand-author the
always-blocks — split the work:
- You (AI) extract the COMPLETE canonical Moore-FSM table from the prose — every
state, every Moore output per state, the reset (state + sync/async + level), and
EVERY transition (one row per state × every input combination; UNROLL a counter
like "falls for >20 cycles" into explicit states — the internal encoding is FREE
because the TB observes only the Moore outputs). Inputs may be a 1-bit port or a
bus bit-select (
in[3]). The format is the docstring ofprograms/moore_fsm_table_emit.py. - The PROGRAM emits + gates:
python3 programs/moore_fsm_table_emit.py --prompt <prompt> --table <your.tbl> --top <TopModule>. It VALIDATES the table is complete and matches the declared interface (rejects a hallucinated port, a missing input combo, an unknown next-state, a missing output) and emits the RTL, or SKIPs (exit 1). The emitted RTL is then your authored sample.
This is the §4.2 AI-step-gated-by-program pattern, not free-text authoring: the
program guarantees the RTL is a pure function of a table it proved complete, so a
mis-extraction becomes a SKIP, never a wrong-but-plausible machine. Proven
0-mismatch on the full Lemmings family (1–4, incl. the 47-state >20-cycle splatter
counter), PS/2 (in[3]), the 3-cycle window counter, and the multi-phase motor
controller. If your first table mismatches its self-TB, RE-READ THE PROMPT (never
the hidden reference) to fix the offending transition/output.
Target-conditional variant recommendations — pick by the DECLARED target, or say why not (#2089)
A design input that ships several implementation variants of one block behind a compile-time parameter usually also says WHICH ONE to pick, and makes that conditional on the implementation target:
"When disabling masking, it is recommended to use the unmasked Canright or LUT S-Box implementation for ASIC or FPGA targets, respectively."
MEASURED (#2089 F21): the authored variant was the FPGA one for a design whose declared target is an open ASIC PDK. Nothing was wrong with the reading of the RTL — the recommendation had never left the document, so there was nothing to read it against.
The deterministic half is already done for you. Phase 1 extracts every such
sentence into L8_RTL_CONSTANTS.target_conditional_recommendations[], one row
per target, each carrying target, recommends, the whole sentence and its
source. "A or B for X or Y, respectively" is distributed (distributive: true); a sentence that DENIES a recommendation ("this is NOT recommended") is
dropped before it reaches you. Do NOT re-read the prose for this — read the rows.
One case is already program-decided — do not re-decide it. Where the
variant is selected by a compile-time parameter whose losing variants the cell
EXCLUDES from staging, the chip_top emitter now derives the value itself: it
narrows to the variants that are staged and consistent with what the input
declared, and among those it takes the one the recommendation names for the
declared target, recording tie_break: "the design input's target-conditional recommendation" with the sentence in rtl/.<top>__param_resolution.json.
READ THAT SIDECAR BEFORE AUTHORING, AND READ ITS tie_break. It says which of
three things happened, and they are not the same answer:
the design input's target-conditional recommendation— the wrapper carries the variant the input recommends. Re-deciding it in the RTL you author is how the two disagree; don't.consuming module's own declared default— the recommendation decided NOTHING here (no declared target, no row for it, no word that separates the survivors, or more than one survivor matched) and the value is a FALLBACK. The judgement is yours again: check it against the rows yourself and say so if you disagree with it.- a
refusalsentry instead of aresolvedone — nothing was chosen and the step will FAIL by name. Declare the parameter; never weaken the check.
What is yours, and why the rest cannot be a program. Everywhere else, pairing a row with THIS design needs the target and the prose together: the declared target comes from L1's tapeout target / L9 / the PDK the run is pointed at, and the recommendation names a variant in the document's own words, not in the RTL's parameter vocabulary. So:
- Read the declared target for this run. An open ASIC PDK is an
ASICtarget; a bitstream flow isFPGA. - If a row's
targetmatches it, author THAT variant and cite the row'ssentencein your handoff. Two rows for the same target that disagree is a finding to report, not a coin to flip. - If you author something else — the recommended variant is not staged, the design input contradicts itself, the parameter has no such value — SAY SO in one line, naming the row you did not follow. Silently authoring the other variant is the defect this section exists to close.
- If no row matches the declared target, author nothing on this basis and say the input made no recommendation for it. An unconditional recommendation is NOT a row here on purpose.
This pairs with the coupling refusal. The same input that recommends a
variant usually also says that setting one parameter obliges another, and the
chip_top emitter REFUSES when the first is satisfied and the second is met by
NOTHING — neither stated by the input nor derived by the resolver above
(COUPLED_PARAMETER_NOT_STATED; the record's satisfied_parameters names the
set it judged). A DERIVED value satisfies the obligation, so you will not see
this refusal on a design whose variant the resolver could work out. When you do
meet it, the fix is to DECLARE the coupled parameter — with the value this
section's rows recommend for the declared target — never to weaken the check.
Guard every declared legal parameter range at elaboration
Before authoring a parameterized module, read every explicit legal range in
the design input. If it says WIDTH >= 5, emit an elaboration guard such as
generate if (WIDTH < 5) begin initial $fatal(1, "WIDTH too small"); end endgenerate. Check the declared default lies inside the range. A parameter
without a stated range needs no invented limit. The deterministic
spec_conformance_check.py reports a missing guard at the Phase-2 handoff.
Skill: Reuse a stable accumulation baseline at the completion edge
When the input requires an iterative computation to keep its previous result readable while busy, separate that observable result from the working state. If a new command selects a constant initialization baseline, and a continuation command selects the unchanged previous result, an extra register bank holding that baseline may duplicate information already available at completion.
Latch the accepted command's baseline selector. Keep the previous result unchanged while busy, then accumulate the stable working state into the selected constant or previous result on the original completion edge. A separate pending-result bank is also unnecessary when no consumer observes it and the working state remains stable until that edge. Retain storage when the input or internal consumers need a snapshot that would otherwise be lost; this is a scheduling choice, not a blanket register removal rule.
Preserve reset aborts, command acceptance, mode latching, chained transactions and the entire external READY/VALID/data timeline. Check those behaviors with native simulation or formal tools, and remeasure mapped area at the same synthesis settings. Moving the final addition can change timing, so synthesis area alone does not establish routed timing, power or physical acceptance.
Skill: Store the index used by critical selection logic
When a native worst path starts at an iteration counter and traverses an index adjustment before a ROM, mux or operand array, store active counts in that consumer's index domain. Reserve other encodings for idle and completion instead of putting increment/decrement and range decoding before a high-fanout selector. Reuse existing state bits when possible. Preserve command acceptance, reset aborts, completion edges and the entire externally visible latency. Compare those external behaviors and remeasure the original signoff corners; a new state encoding alone does not prove timing closure.
The sign-off corner is the SLOW corner, and a chain of adds is what misses it (#2081)
Route an architectural timing failure
Read the selected native STA reports, constraints, corners and the path's cell/interconnect breakdown. If physical repair cannot meet the original period, explain why the limiting logic depth requires an architecture or RTL change. A wrapper's silence does not prove that the architecture is adequate. Keep the signoff corner and original period, and verify the proposed change through native functional/equivalence and timing tools.
A single-cycle datapath authored so that it "looks like the algorithm" reads as correct and closes at the typical corner. The corner the design input declares for sign-off is the SLOW one, and there the SAME netlist misses — not by a margin a resizer can find, but by the delay of carry chains you put in series without deciding to.
The shape to look for: a register-to-register path that computes a sum of THREE
OR MORE operands, or that feeds one sum into another, at the datapath's full
word width. Written the way an algorithm specification writes it, each + maps
to its own ripple carry and the path traverses them end to end. A full-width
ripple carry can be a large fraction of a whole clock period at a slow corner,
so two in series is a miss that no amount of buffering recovers. It will not
show up at the typical corner, and it will not show up until post-route STA on a
design whose route converged, whose DRC was 0 and whose LVS matched.
Three rewrites recover it, all equivalence-preserving, none touching the spec. The first two reduce the number of carry-propagate adds on the path; the third is about the one that is left, and a run that applied only the first two was measured through the front door still VIOLATING its sign-off corner, with a single full-width ripple carry as the dominant term of its worst path (vibe-ic#2228). Stopping after tw
…(truncated)