Hipfire Kernel Tuning

hipfire-kernel-tuning

Land real kernel perf wins without inventing a universal gate, shipping measurement noise, or silently regressing an adjacent arch.

This skill is workflow only. Mutable numbers, noise bands, admission policy, and claim→route maps live in canonical owners under docs/. Do not copy those tables into commits or skill prose.

When to use

• A profile (HIPFIRE_PROFILE, Kernel Atlas, or rocprof) names a hot kernel and you need the right lever.
• You have one candidate change (multi-row, deeper K-tile, wave64, chip override, barrier-free path, hipcc flag) and must prove it on the target arch without breaking others.
• A "should-be-no-op" dispatch refactor needs clean-baseline bisect after a speed-floor warning.
• You have hardware for a chip (e.g. gfx1201) and want an arch-specific fast path beyond a family port.

Read order

1. playbook.md — profile → root-cause → one lever → source/ISA inspect → adjacent-arch boundaries → correctness route → fresh-process measure → reject/log. Start here.
2. levers.md — catalog of patterns that shipped or failed in this tree, with kernel paths under kernels/src/ and commits to read.
3. cross-arch.md — file tags, dispatch fall-through, "no unreachable branches", and when not to flip public dispatch without hardware.
4. case-studies.md — worked wins, fake wins, null results, and silent corruption. Calibrate what "real" looks like before claiming.

Non-negotiable rules

1. One hypothesis, one lever, one commit. Bundle three speculative changes and you cannot bisect a fake win.
2. Profile before editing. No "this feels slow" optimizations.
3. Inspect source + ISA before claiming the bottleneck class. Occupancy, spills, BW%, launch count, and matrix-op mix decide the lever family.
4. Capability predicates gate ISA correctness; they never select a perf sub-variant. Perf picks are measured arch allowlists with a conservative default — see docs/methodology/perf-arch-discipline.md.
5. Correctness route is claim-scoped. Pick the narrowest row in docs/VALIDATION.md. There is no universal GPU gate. Retired coherence-gate-*.sh batteries are not acceptance.
6. Perf claims need the protocol, not a one-shell A/B: docs/methodology/perf-benchmarking.md. Fresh process, warmup, binary/prompt md5, repeated/raw samples, and a surface-matched harness — not bare probe_commits.sh / gates.sh --perf alone (see Supporting tools).
7. Negative results ship. Log the rejection (commit message and/or Atlas task ledger) so the next pass does not re-burn the same hours.
8. No unverified promotion. A local delta is measured, not product default, floor, or admission. Admissions stay in docs/admissions.yml (fail closed when empty).

What's not in this skill

Canonical owners (link; do not duplicate)

Supporting tools (claim-scoped)

Use only when the claim class needs them — full roles in VALIDATION.md:

• Profile: HIPFIRE_PROFILE=1, optional rocprof kernel-trace, Atlas collect-ar / collect-dflash with --profile-* and --isa-*.
• Compile matrix: scripts/compile-kernels.sh for touched chip/family tags.
• Numeric kernel check: target/release/examples/test_kernels (build via hipfire-runtime test_kernels example).
• Speed floor (when policy applies): scripts/speed-gate.sh vs tests/speed-baselines/<arch>.txt.
• Fresh-process A/B: prefer surface-matched harness with repeated refs and raw samples. scripts/probe_commits.sh is Qwen3.5/in-process only (one sample per ref) — not protocol-complete alone. Do not treat scripts/gates.sh --perf as complete evidence (single baseline/HEAD sample plus unrelated Redline/serve arms).
• Path-specific parity oracles: arch-owned dump_*_hidden_states / graph-parity examples when the change can break state — blocked if no oracle exists for that surface.
• Serve semantics only: scripts/serve_harness.py / LFM scripts/serve_harness.py — never numerical parity substitutes.

.agents/skills/hipfire-kernel-tuning/ is the sole executable root for this skill.