readable-verilog-generator

---
name: readable-verilog-generator
description: >-
  Use when creating, writing, reviewing, annotating, repairing, refactoring, or validating readable Verilog RTL, including synthesizable Verilog-2001 .v files, existing-RTL analysis, semantic comment annotation, testbench scaffold planning, ASIC-quality review, local or remote Vivado/xsim validation, evidence-backed repair, and workflow trace diagnosis.
---

# Readable Verilog Generator

Generate, analyze, improve, and verify readable Verilog-2001 RTL through the bundled runtime under `scripts/python/`. Keep design RTL and verification testbenches in `.v` files, use `scripts/python/facade/verilog_api.py` for host integration, and treat formatter-AST and external-tool evidence as stronger than model self-assessment.

## Route

- `create/write`: confirm the design contract, then use `requirements -> codegen_plan -> spec_document -> python -> rtl`.
- `deep_review`: insert a non-empty structured review between the Python semantic model and RTL; it must cover interface, reset, timing/pipeline, handshake or FSM behavior, width, synthesis, testbench coverage, and risks.
- `review/analyze`: remain read-only and report the eight public gate states before suggesting changes.
- `annotate`: preserve an immutable normalized baseline, change only `//` comments, prove token equivalence from that baseline, and rerun the final deliverable gate.
- `repair/refactor`: bind the task to real RTL, reproduce or validate the issue, and apply the smallest evidence-backed change.
- `agentic_repair`: use the existing-RTL `verify_existing_verilog(...)` loop with an explicit `conservative`, `semi_auto`, or `auto_apply` choice.
- `validate`: collect static or external evidence without implicitly editing RTL.

- Load `references/workflows/verilog_dispatcher.md` before routing. Existing assets, logs, waveform clues, and mixed inputs use its read-only entry decision before any generation, validation, backup, or remote action.

## Install v2.0.0

The package root contains `install.ps1`, `install.sh`, and `install.bat` beside this `SKILL.md`. They share the package-local Python backend and read only the generated installer projection under `assets/installer/` plus the same-level bootstrap descriptor. Platform IDs, root resolution, target templates, status text, exit codes, transaction policy, and verification cases are data-driven by `config/installer/`; do not add platform branches or current test values to code or comments.

Install only from a versioned payload with the configured `RELEASE_RECEIPT.json`. Use `--DryRun`/`--dry-run` to validate without creating transaction resources; use replacement flags only when the target and overwrite intent are explicit. A transaction handles one platform and one target, preserves unlisted target files, writes an install receipt, and attempts rollback on failure. Unknown IDs and source directories without a valid release receipt fail closed. See `references/skill/installation.md` for the complete contract and parameterized invocation templates.

## Generate And Modify

1. Confirm module name, ports, clock/reset, behavior, pipeline expectation, interface family, and verification cases.
2. Use `regular` by default; use `deep_review` only when its extra review stage adds value; use `agentic_repair` only for existing RTL.
3. Generate a Python semantic model before RTL in the staged workflow and use it as the testbench semantic contract.
4. Select local interface and ADC/DAC family templates only when the confirmed design matches them; record every adaptation in the requirements and codegen plan.
5. Keep batch execution generation-only, with one run directory per confirmed spec. Do not use batch mode for existing-RTL mutation or decision resume.
6. Treat streaming as provider interaction only. The finalized response artifact remains the extraction source of truth.
7. Run the strict generated-deliverable gate before downstream use. Optional lint and testbench helpers never replace it.

Every module generated or modified by this skill must ship with a same-name `<module>_spec.md` companion. The canonical JSON contract accepts a single legacy module projection or a `modules` array, but each normalized module must declare a safe `.v` `rtl_path`, complete interface ports, clock/reset semantics, cycle behavior, constraints, corner cases, verification cases, and at least one `timing_diagrams` entry. A timing entry contains `id`, `title`, `scenario`, `description`, and WaveJSON with named signals. `python -m scripts.python.workflow.cli write-spec --spec <spec.json> --out-dir <artifact-root> [--source <rtl.v>] --language <zh|en>` writes `spec/<feature>/<module>_spec.md` plus sibling `spec/<feature>/waveforms/<module>_<scenario>.json5` and `.svg`. The `--source` form fails closed when a module or port is undeclared; the no-source form validates and renders only the confirmed spec and never infers behavior from RTL. All waveform rendering goes through the renderer runtime declared by the settings authority and fails closed when its configured Node/npm prerequisites, package identity, version, or executable are unavailable. A render failure stages diagnostics without overwriting the previous valid bundle.

The default profile is `erie_strict`. Its authoritative naming, bilingual header, region, FSM, comment, port-order, runtime-message, and formatter-AST rules live in `references/rules/verilog-code-comment-naming-standard.md`, `references/rules/erie-style.md`, `references/rules/verilog-comment-placement.md`, and machine-readable assets. Do not duplicate those rule catalogs in this entry document.

## Quality

Strict quality control is mandatory. ASIC quality review, independent static lint, and testbench scaffold are optional workflow steps selected only when the task needs their evidence. Optional helper tools are inside the workflow and never replace the generated-deliverable gate.

Generated deliverables must pass the formatter-backed gate with zero errors and zero strict warnings. The public result matrix is exactly `compile`, `ast`, `readability`, `comment`, `naming`, `profile`, `testbench`, and `toolchain`; static compile evidence does not imply that an external simulator, synthesis, or remote validation ran.

Verilog/SystemVerilog filenames must describe real function. Functional digits are valid; VG148 rejects only terminal version or meaningless numeric suffixes. A file recognized as a testbench by `tb_`, `_tb`, `testbench`, or an exact `tb`/`testbench`/`sim` directory must use the `tb_<function>.v` or `tb_<function>.sv` form; `_tb` is recognition evidence, not an allowed output name. When an ordinary design filename carries at least two independent testbench-content evidence groups, VG149 remains inconclusive until the user confirms `design` or `testbench` through `file_role_confirmations`. Confirming `testbench` does not waive the prefix rule: rename the file to the authority-selected `tb_<function>` form before it can pass. VG150 rejects configured workflow/evidence phrases on entity comments and high-confidence periodic unrelated tail families; it does not blacklist ordinary Chinese words or isolated functional descriptions. The full filename and comment contract lives in `references/rules/verilog-code-comment-naming-standard.md`, and gate/report semantics live in `references/rules/verilog-quality-gates.md`.

Use strict mode for new or modified deliverables. `--non-strict --warn-only` is limited to historical reference-corpus analysis and never approves generated output. The formatter backend under `scripts/python/quality/formatter_backend/` is the parser source for quality checks; do not add a second Verilog parser.

For comment-only work, normalize the original RTL once, annotate a copy, run the comment-only verifier with a required delta, run the final gate, and compare the final file again against the immutable baseline. Comments must not change RTL tokens, modules, ports, lvalues, resets, always targets, or instance connections. Reused generic entity comments do not satisfy semantic-comment coverage.

When `VG097` cannot see an external XPM, UNISIM primitive, or project-generated IP interface, first consult the exact-name AMD-Xilinx primitive catalog in `assets/xilinx_primitive_semantics.json` and its detailed contract in `references/rules/xilinx-primitive-exemptions.md`. Keep the result `inconclusive` until a governed pure-interface `.v` source is supplied through the repeatable `--external-interface-source` option when the name is not cataloged or the profile conflicts. Use the registered `quality.external-interface-extract` command for explicit vendor-source module whitelists and `quality.external-interface-manifest` for reviewed project-IP contracts. Never infer that an unknown width is a mismatch, and never use a stub or primitive profile as simulation, synthesis, implementation, or hardware evidence.

Generated RTL must remain synthesizable Verilog-2001. Prefer the governed interface templates for AXI-Stream, AXI4-Lite, AXI4, AHB, and APB; use complete combinational assignments and case defaults; avoid raw gated clocks; document CDC/reset assumptions; keep datapath and control timing-reviewable; and avoid generated `function` or `task` blocks when explicit logic is clearer for waveform debug. Every FSM must use three independent processes for the state register, procedural combinational next-state logic, and state output/task logic; a continuous `assign` to any next-state signal is forbidden. Every continuous or procedural combinational target must pass both the transitive source-cone limit and the configured real-operation budget, each defaulting to at most three. VG146/VG147 evaluate the complete source closure: formatter structured port associations bind child outputs into the parent cone, parameter/localparam specialization selects the materialized implementation, and each definition root, full instance path, specialization fingerprint, and static target remains an independent report identity. Output connections expand through known implementations; inout and unresolved-net boundaries never invent reverse ownership; all known wire/tri drivers are merged; and a clocked output Q cuts upstream expansion while its D input remains checked. The operation budget covers unary, binary, ternary, comparison, selector, control-decode, continuous-assign, combinational-process, clocked D-input, and elaborated `for` operations. Moving logic into `always @(*)` or directly into a clocked D expression does not bypass either gate. If `loop_presence=unknown`, VG146 and VG147 both apply and share the same lower-bound evidence: an over-limit known lower bound fails both, otherwise both remain inconclusive. When the operation budget fails, recommend pipeline registers, registered flags or predecode, or a multicycle FSM decomposition first, and disclose that these changes may alter visible latency; immutable-latency protocols require manual architecture review. Only an exact output bridge from an output port to a clocked internal `_o` `reg` is exempt from the source-cone rule. Detailed VG rules and ASIC review criteria remain authoritative in `references/rules/verilog-quality-gates.md` and `references/rules/asic-verilog-quality.md`.

VG151-VG155 provide module-independent structural contracts. Parameter constraints are selected automatically from the identifiers in each restricted expression; `module`, `instance`, `hierarchy`, and `scope` fields are invalid. VG152 reports large dynamically selected packed storage with a configurable positive threshold and offers structured case/FSM, inferred-memory, or vendor-memory alternatives. VG153/VG154 expose read-without-driver and unused declaration evidence, including reg/wire/function/task facts. VG155 uses explicit top-level ready-valid role facts and requires both valid and ready for a transfer consumer; no target module name is part of these contracts.

Before generating or repairing declarations, apply VG156-VG158 as design-time naming and comment constraints, not only as a final audit. VG156 checks every module/function/task variable declaration by underscore token: a token containing digits is valid only when its complete case-insensitive text appears in the governed protocol/algorithm/rate allowlist. VG157 forbids ordinary-comment version markers such as `v2` or `version 3`; only the formatter-recognized fixed bilingual header and revision-history range is exempt. VG158 repeatedly removes the governed direction/type prefixes and `_o`, then requires at least one functional token outside the closed meaningless-token set; unknown domain terms pass. The formatter must assign each declaration to exactly one region using the shared conflict priority, place the first group comment directly below its banner, place later group comments after exactly one blank line, leave no empty group, keep one trailing blank line per non-empty region, and produce byte-identical output on the second pass.

## Existing RTL

- `analyze_existing_verilog(...)` owns structural analysis and durable design explanation.
- `improve_existing_verilog(...)` owns controlled testbench, style, partition, merge, and optimization assist flows.
- `compare_verilog_semantics(...)` owns equivalence, QoR, and transform-validation evidence.
- `verify_existing_verilog(...)` owns log-driven verification, diagnosis, candidate patches, confirmation resume, and terminal closure.

`optimize_assist` and `merge_assist` are assist-only by default and never silently accept or rewrite source RTL. `conservative` is report-only; `semi_auto` requires confirmation before overwrite; `auto_apply` is valid only after explicit selection and still downgrades non-eligible patch classes to confirmation. Preserve source and testbench backups, diff and decision artifacts, diagnostics, and terminal status exactly as specified by `references/workflows/workflow-contracts.md` and `references/integration/host-integration.md`.

Existing-RTL diagnostic comment findings are advisory so compile, semantic, interface, and high-confidence lint failures remain visible. A report file being written is not success; blocker, warning, failed, toolchain, external-validation, or confirmation-blocked terminal states remain non-success.

## Dependencies And External Evidence

Run dependency preflight before first use and before remote, Vivado, or Vitis work. Missing required dependencies require user approval before installation; if declined, continue only with self-contained static Verilog work and block remote/execute/implement claims. The required skill dependency remains `erie-remote-ssh`; the optional context-engineering group is the only recommended external skill group. No additional external skill suite is included. The required external renderer dependency, package identity, version, executable, and Node/npm floor are read from the settings authority; use `scripts/python/toolchain/wavedrom_runtime.py` with the `check`, `install --yes`, or `render` subcommand, never an ad-hoc package command. Prefer `vivado-developer` and `vitis-developer` for AMD-Xilinx, and `pds-developer` for PangoMicro. FPGA-Agent-Skills remains an explicit manual fallback.

Compile, execute, simulation, synthesis, or implement readiness requires actual external evidence. Remote validation is preferred and must use `erie-remote-ssh`, a user-confirmed server, local-only server selection/configuration, and the remote workdir's `.settings/verilog.remote.json`. A configured default is only a recommendation. Multiple Vivado settings candidates require user selection. Do not silently fall back to local tools and do not add direct SSH/SCP logic.

Remote validation runs are retained by default, including fixed remote-fixture reports. Cleanup occurs only when explicitly requested. Vivado xsim is the preferred simulator backend, followed by VCS+Verdi and then iverilog/vvp; yosys is implement-readiness evidence only. VCS+Verdi support is scripted backend invocation, not full GUI/session automation.

## Document And Command Registry

Registration is enabled for this skill. Markdown remains the authoritative knowledge source. Editable command records live under `config/registry/commands/`; document responsibilities and search metadata have one owner in `config/registry/documents/catalog.json`; current duplicate and interface decisions live in `config/registry/governance/reviews.json`; `config/registry/registry.sqlite3` is a generated local FTS5 trigram index at the location required by the agents-md-generator gate. The skill runtime is self-contained and must not import or call an external `agents-md-generator` registry implementation.

Document governance scans `SKILL.md` and every Markdown file below `references/`, recursively. It records one responsibility per document, knowledge pointers, exact and fuzzy duplicate adjudications, interface mappings, and content hashes. Remove only confirmed equivalent duplication; preserve structural repetition and every unique contract. Installed copies may query and check but must not mutate registry sources.

Detailed command syntax, examples, prerequisites, outputs, exit codes, risk warnings, and relations are retrieved from the local registry:

```text
python -m scripts.python.registry.query_registry ask "<question>" [--kind <kind>] [--category <name>] [--limit 1..10] [--json]
```

The query is read-only and never executes returned commands. Exit codes are `0` for hits, `1` for no match, `2` for request errors, and `3` for a missing, corrupt, stale, or incompatible index. After JSON source changes, use registry instruction `registry.build`; never edit SQLite by hand. See `references/skill/script-guide.md` for the compact registry lifecycle.

## Verify

The first outer command group is the generated-deliverable gate:

```text
python -m scripts.python.validation.generated_deliverable_gate <rtl-file-or-dir> --json <report.json> --markdown <report.md>
```

When either report option is omitted, the CLI writes both reports under the caller's current working directory: `reports/readable/deliverable_gate.json` and `reports/readable/deliverable_gate.md`. The focused quality CLI follows the same policy with `quality_gate.json` and `quality_gate.md`. Supplying one explicit path only overrides that format; JSON and Markdown paths must resolve to different files. Runtime reports must never be written back to the source or installed skill root.

Both CLIs publish v3 reports and print compact `[Python]` finding lines containing the VG rule, status, confirmed location, concrete problem, and direct fix instruction. The JSON and Markdown files contain the full evidence, ordered repair steps, risk and human-review obligation, plus bad/good examples. Exit code `1` means the gate found RTL issues; exit code `2` means invocation, diagnostic-contract, or report-publication failure.

The second outer command group is package validation:

```text
python -m scripts.python.validation.validate_verilog_skill --settings .\config\defaults.json
```

Run the smallest relevant checks while editing, then the governed final chain. The extended repository-regression, external-audit, and remote variants live in `references/integration/configuration.md` and registry instruction `validation.skill`. Local success does not replace requested remote pytest, simulator, synthesis, or installed-copy evidence. Never claim an unrun check passed.

## Resources

- `references/skill/script-guide.md`: registry query, build, document-governance, and command-category contract.
- `references/workflows/verilog_dispatcher.md`: task classification, public gate matrix, and safe repair boundary.
- `references/workflows/workflow-contracts.md`: run artifacts, statuses, resume behavior, and trace semantics.
- `references/integration/configuration.md`: paths, dependencies, remote settings, and validation configuration.
- `references/integration/host-integration.md`: facade functions and host-owned execution boundaries.
- `scripts/python/workflow/spec_document.py`: strict module contract, source cross-check, Markdown and WaveDrom bundle writer.
- `scripts/python/toolchain/wavedrom_runtime.py`: pinned Node/npm/WaveDrom check, explicit install, and SVG renderer.
- `references/rules/verilog-code-comment-naming-standard.md`: canonical readable RTL rule text.
- `references/rules/verilog-quality-gates.md`: VG catalog and report semantics.
- `references/rules/xilinx-primitive-exemptions.md`: exact AMD-Xilinx UNISIM/XPM/project-IP primitive inventory and VG097/VG132/VG146/VG147 boundary contract.
- `references/rules/asic-verilog-quality.md`: ASIC quality review criteria and risk boundaries.
- `references/rules/testbench-patterns.md`: self-checking testbench scaffold patterns.
- `references/checklists/lint-checklist.md`: independent static lint review checklist.
- `references/corpus/verilog-style-observations.md`: empirical ideal/bad corpus observations that do not override normative rules.
- `references/checklists/verilog-readability-gate.md`: final human review.
- `references/skill/skill-standards.md`: skill packaging and progressive-disclosure requirements.

## Boundaries

- Do not generate non-Verilog hardware flows, C/C++ kernels, or alternate RTL dialects.
- Do not invent source RTL, testbenches, logs, successful tool evidence, or repair confirmation.
- Do not store caller run artifacts inside the skill; use caller-selected directories such as `reports/`.
- Do not let optional helpers, model reviews, or registry query results replace actual quality or toolchain evidence.