| name | rtl-document |
| description | Generate Markdown docs for an RTL module (port/param/FSM tables, synth summary) — 'document this module', 'port table', 'refresh RTL docs'. |
| user-invocable | true |
| argument-hint | [module-name | --all] |
| allowed-tools | Bash, Read, Write, Edit, Task, Grep, Glob |
Generate per-module Markdown documentation for SystemVerilog RTL — port table, parameter table, instance table, FSM section, and synthesis summary. Output: docs/rtl/{module}.md.
<Use_When>
- A new RTL module needs documentation.
- Module documentation has become stale after RTL changes.
- A pre-release documentation pass is required.
- The user asks to "document this module", "generate port table", or "refresh RTL docs".
</Use_When>
<Do_Not_Use_When>
- Architecture specification writing is needed → use p2-arch-design.
- IP-XACT XML generation is needed → use rtl-ipxact-gen.
- Synthesis-only reporting is needed → use rtl-synth-check.
</Do_Not_Use_When>
<Why_This_Exists>
RTL documentation written by hand drifts from implementation. Auto-extraction from SV source keeps port tables, parameter lists, and instance trees accurate. The skill splits work between a deterministic parser (objective structure) and the LLM (functional description, FSM semantics, design rationale), making the contract surface explicit and regression-debuggable.
</Why_This_Exists>
Prerequisites
- RTL files exist under
rtl/**/*.sv.
- Optional: synthesis report at
syn/synth_report.txt for area/timing summary.
If the prerequisite is missing: WARNING — recommend running /rtl-agent-team:rtl-p4-implement first. Proceed with available artifacts; the orchestrator adapts scope.
| Path | Role |
|------|------|
| `templates/module-doc-template.md` | Main Markdown skeleton (Overview/Params/Ports/Clocks/Instances/Diagram). |
| `templates/port-table-snippet.md` | Port-table format with `i_/o_/io_` prefix, `{domain}_clk`/`{domain}_rst_n`, kind column. |
| `templates/fsm-section-snippet.md` | FSM table plus Mermaid `stateDiagram-v2` skeleton. |
| `templates/block-diagram-snippet.d2` | D2 block diagram for sub-instance hierarchy. |
| `scripts/extract_module_doc.py` | Verible-based deterministic extractor — emits JSON for ports/params/instances/FSM/conventions. |
| `scripts/render_doc.py` | JSON + template → `docs/rtl/{module}.md` with `` markers. |
| `references/doc-conventions.md` | Naming rules, table format, diagram-tool choice, anti-patterns. |
| `examples/simple_fifo.md` | Small datapath, single domain — minimal baseline. |
| `examples/axi_stream_bridge.md` | AXI4-Stream + APB control, two clock domains — protocol grouping. |
| `examples/cabac_encoder_excerpt.md` | FSM-heavy + sub-instance tree — full template usage. |
<Responsibility_Boundary>
- Scripts handle deterministic extraction: module name, ports, parameters, instances, FSM-candidate states, clock-domain inference from naming, convention violations.
- LLM handles interpretive content: functional description, FSM state semantics, design rationale, integration notes.
<!-- LLM_FILL: ... --> markers in rendered output mark the contract surface. Replace each marker; never delete.
</Responsibility_Boundary>
1. Run `python3 {plugin_root}/skills/rtl-document/scripts/extract_module_doc.py --rtl rtl/{module}/{module}.sv [--syn-report syn/synth_report.txt] --out /tmp/{module}.json` (`{plugin_root}` = plugin root resolved from `.rat/state/spawn-context.json`). If exit code 2 (verible missing), fall back to manual extraction via `rtl-explorer` (see Tool_Usage).
2. Run `python3 {plugin_root}/skills/rtl-document/scripts/render_doc.py --json /tmp/{module}.json --template-dir {plugin_root}/skills/rtl-document/templates/ --out docs/rtl/{module}.md`. The script composes `module-doc-template.md` with the optional snippets — `port-table-snippet.md` when ports exist, `fsm-section-snippet.md` when `fsm_candidates` is non-empty, `block-diagram-snippet.d2` when there are two or more instances.
3. Read `skills/rtl-document/references/doc-conventions.md` once for naming/format/diagram rules.
4. Open at least one matching `skills/rtl-document/examples/*.md` for tone reference — pick the example whose complexity (small / multi-domain / FSM-heavy) is closest to the target module.
5. Replace every `` marker in `docs/rtl/{module}.md`. Apply to all such markers in the file — do not stop after the first.
6. Report the generated file path to the user.
Apply steps 1-6 to every requested module. When --all is passed, fan out using one task per module in parallel.
<Tool_Usage>
Manual-extraction fallback (when verible is unavailable):
Task(subagent_type="rtl-agent-team:rtl-explorer",
prompt="Document RTL module per skills/rtl-document/. Read rtl/{module}/{module}.sv, extract ports/parameters/instances/FSM, apply project naming conventions, and fill the LLM_FILL markers in docs/rtl/{module}.md.")
Synthesis summary:
Task(subagent_type="rtl-agent-team:synthesis-reporter",
prompt="Summarize syn/synth_report.txt and syn/timing_report.txt for the docs/rtl/{module}.md synthesis section.")
</Tool_Usage>
Small datapath module, no FSM, single clock domain.
skills/rtl-document/examples/simple_fifo.md
Port table only; FSM and D2 sections omitted by render_doc.py because the JSON has empty fsm_candidates and one instance or fewer.
AXI-Stream bridge with two clock domains.
skills/rtl-document/examples/axi_stream_bridge.md
Ports grouped by AXI / APB; Clock Domains table lists both `sys` and `pixel`; D2 block diagram shows the async-FIFO bridge.
FSM-heavy codec module with multiple sub-instances.
skills/rtl-document/examples/cabac_encoder_excerpt.md
FSM table with Mermaid `stateDiagram-v2`; D2 block diagram for the sub-instance tree; functional description references the relevant standard section.
<Escalation_And_Stop_Conditions>
extract_module_doc.py returns SV parse error → report file:line; do not fabricate ports. Ask the user to fix the syntax first.- FSM register cannot be inferred → JSON has
fsm_candidates: []. Add an FSM section manually only when a state machine clearly exists and the state register is identifiable.
- Synthesis report absent → omit the Synthesis Summary section; note the absence in the document footer.
- Port name violates convention (e.g.,
data_i suffix) → record in convention_violations and surface the violation at the top of the generated doc. Do not rewrite the RTL.
</Escalation_And_Stop_Conditions>
Output
docs/rtl/{module}.md — per-module documentation./tmp/{module}.json — intermediate extraction (transient; not committed).
<Final_Checklist>
