guide-performance-optimization

name

guide-performance-optimization

description

Diagnose RISC-V performance root causes and give evidence-based guidance without editing code, generating patches, or choosing implementations. Use for a named function or hot region with perf annotate or perf report, objdump or llvm-objdump disassembly, and optional perf stat, readelf -A, or hwprobe; or for RISC-V/RVV performance questions about unvectorized loops, vsetvl, LMUL/register groups, fixed-width VLEN/LMUL, packed low-bit decoding, hand-written assembly, matrix-engine or packed-SIMD offload, control flow or layout, register pressure, FP, traps, JIT codegen, timers, interrupts, privileged CSRs, glibc, Go, or crypto. Supports profile-backed diagnosis, labeled static-only analysis, and comparison of a few functions measured with the same event, input, and window. Do not use for non-RISC-V targets, isolated instruction/CSR/extension semantics, code-change or patch requests, or implementation selection. With no profile or disassembly, return a constrained hypothesis-only blueprint without asking.

Guide Performance Optimization

Analyze RISC-V performance bottlenecks from single-function perf annotate output, with optional perf stat, and provide bounded optimization guidance.

Scope

Deliver exactly four things: profile evidence, a root-cause blueprint, the complete The fix guidance that directly corresponds to the root cause, and a falsifiable verification forecast. Do not edit source code, generate or apply a patch, or enter a user interaction about whether to implement a change or which implementation to choose. This paragraph is the only short statement of that boundary. The normative definition is the Output boundary in triggers/arbitration.md; the corresponding self-check is item 7 of Phase 6 in references/output-contract.md.

This skill is self-contained for RISC-V profiling analysis. Do not delegate RISC-V profile classification or Pattern handoff to another skill.

Entry conditions

Select exactly one of four mutually exclusive modes according to the available artifacts. Each mode limits the strength of permitted conclusions.

Mode	Input	Permitted conclusions	Confidence ceiling
A. Profile-backed (profile_backed)	Complete single-function perf annotate, optionally with perf stat	All conclusions, including dynamic hotspot share and a benefit upper bound, subject to the four Phase 1 sampling-semantics constraints	No additional ceiling
B. Incomplete annotate (annotate_incomplete)	Annotate covers only cold setup or epilogue and omits the hot-loop body	Report the coverage gap, cold-interval facts, and hypothesis-only candidates supported by the user's description or static artifacts; never promote a cold-interval match to the hotspot root cause	Route confidence at most Medium; impact confidence must be Low
C. Static-only (static_only)	Disassembly from objdump, llvm-objdump, or a project assembly dump, but no profile	Dependency-chain length, instruction combinations and issue constraints, alignment and memory-access shapes, RVV or extension feasibility, and agreement between ISA and build	Impact confidence at most Low; label static_only
D. No artifact (hypothesis_only)	Neither a profile nor disassembly	hypothesis-only conclusions as defined by the same-named branch in references/output-contract.md	Route confidence at most Medium; impact confidence must be Low

In mode C, never report dynamic hotspot proportions, cycle attribution, sample share, an Amdahl benefit upper bound, or any workload-level benefit judgment: static disassembly contains no execution-frequency information. In Phase 3, quote original disassembly lines with their addresses and instructions and mark them no percentage column: static-only. In Phase 5, state the minimum single piece of data required to upgrade the conclusion to profile-backed.

In mode D, record annotate_gap: no annotate, retain the section structure, and replace the Phase 3 verbatim quote with hypothesis-only. Never invent an annotate line with an address or percentage in mode C or D.

The absence of whole-program hotspot ranking or a call-stack visualization is not a gap; do not request either. Ask a question only for the object-clarification exception in references/output-contract.md, when even the function or target under analysis cannot be determined. For baseline and evidence gaps, record the gap and offer an optional acquisition command. Classify tool and permission failures according to references/failure-recovery.md; never degrade silently.

Flow

1. Read references/output-contract.md for the exact seven section headings, the B/C/D substitutions, the th.v* baseline gate, narrow-question exemption, object-clarification exception, forbidden shortcuts, and Phase 6 completion gate.
2. Read references/profile-flow.md for the Phase 0-6 actions and criteria. Read per-phase output requirements in references/output-contract.md and the two confidence axes in references/confidence-rules.md, which grade route-gate, root-cause, and impact evidence separately. Apply the matrix in references/failure-recovery.md to acquisition or permission failures; never degrade silently or ask merely because a failure occurred.
3. Read Step 0 of triggers/from-profile.md. Establish the hardware ISA, build ISA, vector flavor, VLEN, bound type, and three routing dimensions. Derive required class files from provenance, stack, and symbol evidence, extend the scan set only with independently observable supplemental signals, and record an include or exclude reason for all eight classes.
4. Read every selected class file in full and evaluate every row. Match profile signals to one or more files under patterns/. The class index only selects files; the inline criteria in rows-*.md are the sole source of truth for signal-to-Pattern routing and exclusions. Write Classes scanned: in Phase 3.
5. For multiple matches, no match, and the output boundary, read triggers/arbitration.md, including the L0-L4 causal hierarchy, primary ownership decision, and negative-evidence reporting order.
6. After a match, read the corresponding patterns/*.md file before producing the root-cause blueprint. Phase 4 must cite content unique to that Pattern; naming only a section heading does not demonstrate that the file was read.

Local references

Use references/kernel-conventions.md for __riscv_v* intrinsic-kernel unrolling, LMUL budgets, fixed-VL loops, extension guards, and verification; references/vector-math-conventions.md for the shared vector-math contract used by activation and normalization; references/isa-extensions.md for extension, detection-channel, and routing mappings; and references/core-profiles.md for silicon execution models, vector flavor, and VLEN. For bottlenecks inside an existing hand-written vector or SIMD .S implementation, use patterns/riscv-assembly-kernel-performance-optimization.md. For a missing .S implementation established by all four policy and existence proofs, use patterns/policy_backed_missing_riscv_assembly_kernel.md.

Use these references only as technical background for explaining the root cause, The fix, and verification forecast. Do not convert them into direct implementation tasks or let them replace disassembly inspection, testing, or benchmarking.

Output contract

Begin the diagnostic deliverable with this commitment: Functions under analysis: [...] (N functions) -> this output contains N sets of Phase 3-5. Then include these seven headings verbatim:

## Phase 0 — Evidence inventory
## Phase 1 — Baseline
## Phase 2 — Scope
## Phase 3 — Pattern scan: <function>
## Phase 4 — Root-cause blueprint: <function>
## Phase 5 — Verification forecast: <function>
## Phase 6 — Completion check

For multiple functions, repeat Phases 3-5 in function order. The minimum content for each section, B/C/D substitutions, th.v* gate, narrow-question exemption using Contract skipped:, and object-clarification exception are in references/output-contract.md. Insufficient evidence changes section content through explicit gap labels; it never permits omitting a section or stopping early.