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.
Apply steps 1-6 to every requested module. When --all is passed, fan out using one task per module in parallel.
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.")
Output
docs/rtl/{module}.md — per-module documentation./tmp/{module}.json — intermediate extraction (transient; not committed).
1---2name: rtl-document3description: Generate Markdown docs for an RTL module (port/param/FSM tables, synth summary) — 'document this module', 'port table', 'refresh RTL docs'.4---56<Purpose>7Generate per-module Markdown documentation for SystemVerilog RTL — port table, parameter table, instance table, FSM section, and synthesis summary. Output: docs/rtl/{module}.md.8</Purpose>910<Use_When>11- A new RTL module needs documentation.12- Module documentation has become stale after RTL changes.13- A pre-release documentation pass is required.14- The user asks to "document this module", "generate port table", or "refresh RTL docs".15</Use_When>1617<Do_Not_Use_When>18- Architecture specification writing is needed → use p2-arch-design.19- IP-XACT XML generation is needed → use rtl-ipxact-gen.20- Synthesis-only reporting is needed → use rtl-synth-check.21</Do_Not_Use_When>2223<Why_This_Exists>24RTL 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.25</Why_This_Exists>2627## Prerequisites2829- RTL files exist under `rtl/**/*.sv`.30- Optional: synthesis report at `syn/synth_report.txt` for area/timing summary.3132If the prerequisite is missing: WARNING — recommend running `/rtl-agent-team:rtl-p4-implement` first. Proceed with available artifacts; the orchestrator adapts scope.3334<Assets>35| Path | Role |36|------|------|37| `templates/module-doc-template.md` | Main Markdown skeleton (Overview/Params/Ports/Clocks/Instances/Diagram). |38| `templates/port-table-snippet.md` | Port-table format with `i_/o_/io_` prefix, `{domain}_clk`/`{domain}_rst_n`, kind column. |39| `templates/fsm-section-snippet.md` | FSM table plus Mermaid `stateDiagram-v2` skeleton. |40| `templates/block-diagram-snippet.d2` | D2 block diagram for sub-instance hierarchy. |41| `scripts/extract_module_doc.py` | Verible-based deterministic extractor — emits JSON for ports/params/instances/FSM/conventions. |42| `scripts/render_doc.py` | JSON + template → `docs/rtl/{module}.md` with `<!-- LLM_FILL: ... -->` markers. |43| `references/doc-conventions.md` | Naming rules, table format, diagram-tool choice, anti-patterns. |44| `examples/simple_fifo.md` | Small datapath, single domain — minimal baseline. |45| `examples/axi_stream_bridge.md` | AXI4-Stream + APB control, two clock domains — protocol grouping. |46| `examples/cabac_encoder_excerpt.md` | FSM-heavy + sub-instance tree — full template usage. |47</Assets>4849<Responsibility_Boundary>50- **Scripts** handle deterministic extraction: module name, ports, parameters, instances, FSM-candidate states, clock-domain inference from naming, convention violations.51- **LLM** handles interpretive content: functional description, FSM state semantics, design rationale, integration notes.52- `<!-- LLM_FILL: ... -->` markers in rendered output mark the contract surface. Replace each marker; never delete.53</Responsibility_Boundary>5455<Execution>561. 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).572. 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.583. Read `references/doc-conventions.md` once for naming/format/diagram rules.594. Open at least one matching `examples/*.md` for tone reference — pick the example whose complexity (small / multi-domain / FSM-heavy) is closest to the target module.605. Replace every `<!-- LLM_FILL: ... -->` marker in `docs/rtl/{module}.md`. Apply to all such markers in the file — do not stop after the first.616. Report the generated file path to the user.6263Apply steps 1-6 to every requested module. When `--all` is passed, fan out using one task per module in parallel.64</Execution>6566<Tool_Usage>67Manual-extraction fallback (when verible is unavailable):68```69Task(subagent_type="rtl-agent-team:rtl-explorer",70 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.")71```7273Synthesis summary:74```75Task(subagent_type="rtl-agent-team:synthesis-reporter",76 prompt="Summarize syn/synth_report.txt and syn/timing_report.txt for the docs/rtl/{module}.md synthesis section.")77```78</Tool_Usage>7980<Examples>81<example index="1">82<scenario>Small datapath module, no FSM, single clock domain.</scenario>83<reference>examples/simple_fifo.md</reference>84<expected_output>Port table only; FSM and D2 sections omitted by render_doc.py because the JSON has empty fsm_candidates and one instance or fewer.</expected_output>85</example>8687<example index="2">88<scenario>AXI-Stream bridge with two clock domains.</scenario>89<reference>examples/axi_stream_bridge.md</reference>90<expected_output>Ports grouped by AXI / APB; Clock Domains table lists both `sys` and `pixel`; D2 block diagram shows the async-FIFO bridge.</expected_output>91</example>9293<example index="3">94<scenario>FSM-heavy codec module with multiple sub-instances.</scenario>95<reference>examples/cabac_encoder_excerpt.md</reference>96<expected_output>FSM table with Mermaid `stateDiagram-v2`; D2 block diagram for the sub-instance tree; functional description references the relevant standard section.</expected_output>97</example>98</Examples>99100<Escalation_And_Stop_Conditions>101- `extract_module_doc.py` returns SV parse error → report file:line; do not fabricate ports. Ask the user to fix the syntax first.102- 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.103- Synthesis report absent → omit the Synthesis Summary section; note the absence in the document footer.104- 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.105</Escalation_And_Stop_Conditions>106107## Output108109- `docs/rtl/{module}.md` — per-module documentation.110- `/tmp/{module}.json` — intermediate extraction (transient; not committed).111112<Final_Checklist>113- [ ] `docs/rtl/{module}.md` exists for every requested module.114- [ ] Port table lists every port with `i_/o_/io_` prefix; clock/reset rows tagged `kind=clock|reset`.115- [ ] Parameters use `UPPER_SNAKE_CASE`.116- [ ] Instance table uses `u_` prefix.117- [ ] All `<!-- LLM_FILL: ... -->` markers replaced.118- [ ] RTL source not modified.119- [ ] Synthesis Summary included when `syn/synth_report.txt` exists.120- [ ] Convention violations flagged at the top of the doc when any were found.121</Final_Checklist>
babyworm