| name | rtl-p5s-perf-verify |
| description | P5 performance verification: RTL throughput/latency/stalls vs BFM baseline. Triggers 'measure throughput', 'performance regression', 'latency vs BFM'. |
| user-invocable | true |
| argument-hint | [module-name] |
| allowed-tools | Bash, Read, Write, Edit, Task, Grep, Glob |
Measure RTL performance (throughput, latency, stall cycles) against BFM-predicted baselines and flag deviations exceeding 10%. Outputs: `sim/{module}/{module}_perf.json` (raw measured vs expected metrics) and `reviews/phase-5-verify/{module}-performance-report.md` (PASS/FAIL verdict with deviation analysis).
<Use_When>
- RTL passes functional verification and performance validation is the next step.
- A BFM performance baseline exists in
bfm/perf_baseline.json.
- A performance regression needs quantification after an RTL change.
</Use_When>
<Do_Not_Use_When>
- BFM does not exist yet — run
bfm-develop first.
- Functional correctness is not yet established — run
rtl-p5s-func-verify first.
- Synthesis timing analysis (setup/hold slack) is needed — use
rtl-synth-check instead.
</Do_Not_Use_When>
<Why_This_Exists>
RTL that is functionally correct may still fail performance targets due to unexpected stalls, backpressure, or pipeline bubbles invisible to functional tests. BFM provides the performance baseline; RTL must match it. Separating performance measurement from functional verification keeps each pass focused and regressions attributable.
</Why_This_Exists>
Prerequisites
rtl/**/*.sv files must exist.bfm/perf_baseline.json must exist.
If prerequisites are missing: WARNING — recommend running /rtl-agent-team:rtl-p5s-func-verify and /rtl-agent-team:bfm-develop first. Orchestrator adapts scope with available artifacts.
| Path | Role |
|------|------|
| `templates/perf-monitor-template.sv` | SV measurement harness scaffold: cycle counter, throughput/latency monitors wired to DUT ports. |
| `scripts/parse_perf_report.py` | Deterministic comparator: parses the perf-monitor summary block from the sim run log, compares against `bfm/perf_baseline.json`, writes `{module}_perf.json` with per-metric delta_pct/verdict (10% threshold; exit 1 on FAIL). |
| `references/perf-verify-conventions.md` | Metric naming, JSON schema, 10% deviation threshold, report structure, anti-patterns. |
| `examples/` | Worked example: sample run log + baseline + generated `cabac_encoder_perf.json` + README with the exact command and metric arithmetic. |
<Responsibility_Boundary>
- Scripts handle deterministic measurement: cycle counters and throughput monitors in the SV harness produce raw numeric values written to the JSON output.
- LLM handles interpretive analysis: deviation root cause (which pipeline stage contributes stalls), recommendation text, and BFM vs RTL gap narrative.
- Contract surface:
{module}_perf.json schema and report structure documented in references/perf-verify-conventions.md.
</Responsibility_Boundary>
1. Read `references/perf-verify-conventions.md` for the JSON schema, 10% deviation threshold, and report structure.
2. Spawn `p5s-perf-orchestrator` (see Tool_Usage) to execute performance simulation using `templates/perf-monitor-template.sv` as the measurement harness scaffold.
3. The orchestrator reads `bfm/perf_baseline.json`, runs the simulation, and writes `sim/{module}/{module}_perf.json` with measured vs expected values and per-metric PASS/FAIL verdicts. For deterministic comparison it can run `python3 {plugin_root}/skills/rtl-p5s-perf-verify/scripts/parse_perf_report.py --log sim/{module}/{module}_perf_run.log --baseline bfm/perf_baseline.json -o sim/{module}/{module}_perf.json` (`{plugin_root}` = plugin root resolved from `.rat/state/spawn-context.json`; see `examples/README.md` for flags).
4. The orchestrator writes `reviews/phase-5-verify/{module}-performance-report.md` with the metrics table, deviation analysis for any failing metric, and a recommendation.
5. Report the overall PASS/FAIL verdict and the report path to the user.
Apply steps 1-5 to every requested module — do not stop after the first.
<Tool_Usage>
Performance orchestration:
Task(subagent_type="rtl-agent-team:p5s-perf-orchestrator",
prompt="Execute performance verification. User input: $ARGUMENTS")
Do not perform simulation work directly — the orchestrator manages performance simulation, BFM baseline comparison, throughput/latency/stall measurement, and deviation flagging.
</Tool_Usage>
Video encoder module after a pipeline rebalancing change; throughput must match BFM baseline within 10%.
examples/
JSON reports throughput 480 Mbps measured vs 500 Mbps expected (4% delta → PASS); latency 12 cycles vs 12 expected (0% → PASS); overall PASS. Report recommends proceeding to `rtl-p6-design-review`.
RTL change introduced a pipeline bubble; stall cycles exceed baseline by 15%.
examples/
JSON reports stall_cycles_pct 23% measured vs 8% expected (188% delta → FAIL); overall FAIL. Report identifies the added pipeline register at the output FIFO as the contributor; recommends inspecting `rtl/encoder/output_buffer.sv`.
`bfm/perf_baseline.json` is absent before BFM development is complete.
examples/
WARNING emitted: `bfm/perf_baseline.json` not found — recommend running `/rtl-agent-team:bfm-develop` first. Skill does not proceed to simulation.
<Escalation_And_Stop_Conditions>
bfm/perf_baseline.json absent → emit WARNING; do not fabricate baseline values; stop.- Simulation fails to compile or run → report the error; do not report performance metrics.
- Deviation exceeds 10% → report FAIL with deviation analysis; do not auto-accept.
- Performance bottleneck requires RTL-level investigation → flag the suspected module and signal path; do not modify RTL.
</Escalation_And_Stop_Conditions>
Output
sim/{module}/{module}_perf.json — raw measured vs expected metric values with per-metric PASS/FAIL.reviews/phase-5-verify/{module}-performance-report.md — throughput and latency table vs BFM baseline, deviation analysis, PASS/FAIL verdict.
<Final_Checklist>
