# Hipblaslt Pr Quality

> hipBLASLt supplements to the ROCm PR quality base skill. Use for hipBLASLt PR author, review, or pre-merge gating (target branch develop; product paths under projects/hipblaslt/**, including tensilelite/, and shared/stinkytofu/**, the instruction scheduler and hazard pass that hipBLASLt kernels go through). Adds and tightens base rules; never relaxes a base MUST.

- Skill: `rocm/hipblaslt-pr-quality` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx get-skill add rocm/hipblaslt-pr-quality`
- Raw SKILL.md: https://api.skillmd.com/api/skills/rocm/hipblaslt-pr-quality/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: rocm (https://skillmd.com/u/rocm)
- Updated: 2026-11-15
- Page: https://skillmd.com/skills/rocm/hipblaslt-pr-quality

---


# hipBLASLt PR Quality (overlay)

## Dependency (mandatory — do this first)

Read and apply the `rocm-pr-quality` base skill before anything below. It lives in `ROCm/TheRock`
at `skills/rocm-pr-quality/` (`SKILL.md` + `reference.md`). Since `rocm-libraries` is a submodule of
TheRock, a normal TheRock checkout already has the base present alongside this overlay.

The supplements here only **ADD** rules or **TIGHTEN** thresholds. They never relax a base MUST-rule.
On any conflict, the base MUST-rule wins.

---

## Scope

- **Target branch:** `develop`.
- **Product paths:** `projects/hipblaslt/**` (the hipBLASLt component root, including `tensilelite/`)
  and `shared/stinkytofu/**` (stinkytofu, the assembly-level instruction scheduler and hazard pass
  that TensileLite runs on generated kernels).
- Paths below are written relative to the repo root; in a standalone hipBLASLt checkout they are relative to `projects/hipblaslt/`.
- Changes outside these (docs, repo tooling) follow the base bar only.

---

## Supplements

### Scoping of base rules (adds)
Bind the base change-classes and scope buckets to hipBLASLt paths:
- Frontend / API: `projects/hipblaslt/library/include/hipblaslt/**` (public headers), `projects/hipblaslt/library/src/**`.
- TensileLite / kernel generation: `projects/hipblaslt/tensilelite/**`, especially `KernelWriter*.py`.
- Tests/clients: `projects/hipblaslt/clients/**`.
- Kernel scheduling and hazard safety: `shared/stinkytofu/**` (see the `hazard-safety` class below).

### Tightens M1 (defect-fix regression test)
The regression test for a defect fix must run in a **shared CI lane** (TheRock GitHub Actions or
Math CI; not local-only) for the affected gfx arch. A local-only repro does not satisfy M1 for
hipBLASLt.

### Adds H1 — known-bug two-PR flow
Known-bug entries live in `projects/hipblaslt/clients/tests/data/known_bugs.yaml` with a tracker
id and a time-box. This is the concrete implementation of the base "track and time-box
quarantines" requirement. Waiver code **`W-KNOWN-BUG`** declares a tracked two-PR plan.


### Adds — TensileLite test levels (maps the base test-level SHOULD to real lanes)
C++ unit → TensileLite pytest → client/API → integration → perf. Pick the lowest level that fails on
the regression. Map the base test-level table onto these lanes when advising or reviewing.

### Adds — TensileLite test levels (maps the base test-level SHOULD to real lanes)
C++ unit → TensileLite pytest → client/API → integration → perf. Pick the lowest level that fails on
the regression. Map the base test-level table onto these lanes when advising or reviewing.

### Adds — characterization snapshot (`.ambr` golden) discipline
Scope: `projects/hipblaslt/tensilelite/tensilelite/Tests/unit/characterization/` — characterization tests
that pin TensileLite's *current* Python behavior as syrupy `.ambr` goldens, run in the `-m unit`
lane. Green means "behavior unchanged," not "correct"; a red is information about the PR's own
change. When a PR's diff touches any `.ambr` file, gate on all of the below.
- **Classify the red first.** The author must say which of three a golden change is: (a) an intended
  behavior change, (b) a real bug the golden just caught — fix the source, leave the golden alone, or
  (c) a fragile/non-deterministic test — make it deterministic (e.g. the `{basename, err}` digest /
  canonicalization). Never re-record to mask churn, never weaken production source to stabilize a
  golden, and never delete a failing test to go green.
- **Surgical, never blanket.** Update goldens only on the smallest affected node
  (`pytest <node-id> --snapshot-update`) and review every `.ambr` diff line. A blanket
  `pytest -m unit --snapshot-update` is forbidden: while CI stays green it blesses real regressions,
  re-records vacuous goldens nobody read, un-pins deliberately-pinned bugs, and bakes in
  non-determinism. A PR whose `.ambr` diff spans many unrelated nodes/files is rejected and re-scoped
  to the nodes the behavior change actually affects.
- **ADR required for pinned or changed behavior.** A golden that pins known-wrong behavior, or any
  non-obvious golden change, MUST land with an Architecture Decision Record under
  `.../characterization/adr/`: one short, append-only file per decision in Nygard form
  (`Status` / `Context` / `Decision` / `Consequences`), carrying a `Defect:` tracker link when a real
  bug is pinned. ADRs are *superseded*, not edited in place — if a later fix flips the golden, update
  the golden and supersede the ADR. (The running catalog of pinned behaviors / accepted mutants stays
  a registry, e.g. `DECISIONS.md`, not one ADR each.) A behavior-changing `.ambr` diff with no
  matching ADR does not pass review — the concrete hipBLASLt form of the base "document intentional
  behavior changes" rule.
- **Stable-arch goldens are a regression signal.** On stable archs (gfx908 / gfx90a / gfx942) a
  codegen-digest golden change is a suspected compiler/codegen regression: require explicit
  root-cause and sign-off (ADR + PR description) before accepting the new golden. Newer, still-churning
  archs may keep a few compiler generations side by side.
- **Re-run before push.** After recording, the node is byte-identical on two further
  `--snapshot-update`-free runs, and the full `-m unit` suite stays green.

References: the characterization `README.md` ("Snapshot / golden discipline") and the `adr/` records.

### Adds — gfx CI labels
Component CI vocabulary: `ci:gpu:<gfx>`, `ci:extended`, `ci:performance`. Labels select coverage;
they never waive the base test/flag policy. Discover the live label/gfx set from the repo's CI
config rather than hardcoding it.

### Tightens — device/architecture coverage
Kernel-generation and assembly changes must show coverage on the affected gfx arch(s) in CI, not
just host-side tests. Treat a build-only-but-untested arch as uncovered.

### Adds — `hazard-safety` change class (stinkytofu, waits, hazards, scheduling)
Some GPU architectures leave certain register hazards to software. For example, in gfx1250's expert
scheduling mode 2 the hardware does not stall an instruction that overwrites a register a matrix
instruction is still reading; the compiler must insert an `s_wait_alu` instead. stinkytofu's wait
passes are then the only guard, and a missed wait gives a silently wrong answer, not a crash.
Text-matching tests (FileCheck) show what the pass emits; they cannot show that a hazard is covered.

Tag a PR `hazard-safety` when it adds, removes, weakens or gates a wait or hazard rule, changes the
instruction scheduler's dependency handling, or edits instruction or hardware tables. Paths include
`shared/stinkytofu/**/InsertWaitAluPass*`, `RemoveWaitAlu*`, the waitcnt passes, `dag/CDNA5.hpp`,
`HazardRules.hpp`, `HWModel*`, `HwReg*`, `hardware/**/*.def`, and rocisa's hazard tables. When unsure,
tag it (stricter wins). A `hazard-safety` PR must have all of:
- **A safety argument** in the description for each rule it adds, removes, weakens or gates: why the
  hazard cannot occur, or why the remaining wait still covers it.
- **Execution evidence on the target architecture.** Either differential execution (the same kernels
  built with and without the change give bitwise-identical results on integer test data) or a small
  per-rule test kernel run on hardware, with run counts. Host-only ctest and FileCheck results do not
  satisfy this.
- **A test that fails if the protection is removed or the gate is flipped,** not only one that matches
  today's emitted text.
- **The protection on by default** (see the M2 tightening below). A gate that weakens a protection
  ships with the protection on until the evidence lands.

Missing any of these is `BLOCKING`. This tightens the base device-coverage rule for this class: a
build-only or emulator-only result does not count as coverage.

### Tightens M2 — a safe default for a protection is "on"
The base M2 accepts a "safe-default flag." For a new feature the safe default is usually off. For a
hazard or correctness protection it is the reverse: the safe default keeps the protection **on**. A
new gate whose default turns a protection off does not satisfy M2. A gate described as temporary or
for debugging never merges enabled.

### Adds — test-substance smell: assertions on source text
Add to the base smell scan: a test that reads a source file and asserts it contains a string (for
example, that `Solution.py` contains `state["ProblemType"]["Sparse"]`). It fails only if someone
edits that string, so it says nothing about behavior. Treat a hit as `BLOCKING`, like the base smells.

### Tightens — stale-base on high-coupling files
Make the base stale-base check concrete and stricter. High-coupling files:
`KernelWriter*.py` (which already covers `KernelWriterAssembly.py`), register/SGPR-lifetime code, shared `Components/*`.
Overlap with the base branch on any of these since the PR diverged → **mandatory** rebase + re-run
(base default is strong-recommend).

### Tightens — stale-base on validator vs. validated-data (no file overlap)
Some merge-time breakage has **no file overlap at all**: one PR changes a *validator or allow-list*
while another adds *data the validator checks*. Treat these as a coupled pair even though they touch
different paths. The concrete hipBLASLt instance:
- Validator / allow-list: `projects/hipblaslt/tensilelite/tensilelite/Common/GlobalParameters.py` (the
  global-parameter registry and the `_assertGlobalParametersAreValid` ignored-key allow-list), plus
  the enforcing test `projects/hipblaslt/tensilelite/tensilelite/Tests/unit/test_input_yaml_corpus_clean.py`.
- Validated data: YAML fixtures under `projects/hipblaslt/tensilelite/tensilelite/Tests/**` (e.g.
  `common/gemm/**`).

If, since the PR diverged, the base branch changed the validator/allow-list **and** this PR adds or
edits validated data (or vice-versa), neither PR's own CI can see the collision → **mandatory**
rebase + re-run the strict-corpus test (`test_input_yaml_corpus_is_strict_clean`) before merge.
Generalize the check: when a PR *narrows* an allow-list/schema, scan the base for in-flight PRs
adding data the new rule would reject; when a PR *adds validated data*, confirm the allow-list/schema
on the merge-target still accepts it.

### Tightens — approvals
Changes to the high-coupling files above need **≥ 2 hipBLASLt code-owner approvals** after the
local team review (stricter than a generic base approval count). A `hazard-safety` PR also needs at
least one approval from a reviewer outside the author's immediate team.

### Adds — prose and style for written artifacts
When writing the PR description, review comments, handoffs, or design notes, apply the style guide in
[`prose-style-context.md`](prose-style-context.md) (same directory). It sets the reader model,
length limits, the sentence-level gate, warning-word list, and the evidence/scope discipline for
prose. It governs how findings are written; it never relaxes a base or overlay MUST-rule.

### Adds — recommend a description rewrite (author and review)
Both **Author assist** and **Review assist** must produce a concrete recommended PR-description
rewrite, not just a critique.
- **Author:** after drafting the description from the base template, run the draft through the
  `prose-style-context.md` sentence-level gate and final acceptance test, then present the revised
  description as the recommendation.
- **Review:** read the PR's current description, check it against the same gate, and when it fails
  any check (undefined term, vague-improvement or hand-waving word, missing evidence/scope,
  repetition or length that obscures the change, or a heading that cannot be answered from the
  body) output a specific rewrite the author can paste in. Cite which gate items failed.
- The rewrite is **advisory**. Per base operating principle 1, never post it to GitHub or edit the
  PR without explicit human approval; present it in the chat/`BLOCKING`-items output only. Preserve
  every repository-required heading and the JIRA/issue line.

### Adds — `W-TUNE`
Component-specific waiver for tuning-only PRs, on top of the base waiver set.

### Tightens M5 — tracker linking
A Jira key (`AIHPBLAS-` or `ROCM-`) in the branch name or PR title triggers Jira's dev-panel
auto-linking, creating the reverse edge automatically. Prefer this so M5's links resolve in both
directions.

### Adds — risky-moment region (configure the base timing gate)
hipBLASLt spans a Taiwan-based team (MI300 focus) and a North-American team (MI350 focus). The
pre-merge timing gate should weigh the **owning team's** region/timezone for "going into the
weekend / end of day," not just the author's local clock. Concrete weekend windows: Taiwan team
UTC+8 Fri 17:00 – Mon 09:00; NA team UTC-7 Fri 17:00 – Mon 09:00. A merge touching a high-coupling
file inside the owning team's window should defer or require explicit owner sign-off.

---

## What the overlay cannot do
Drop the regression-test-on-defect rule, allow disabling tests to green CI (M3), or skip work
tracking on a non-trivial PR. Those are base MUSTs; the overlay can only make them stricter.

---

## Worked example this overlay is designed to catch
PR #7796 (StaggerU for TDM) was green ~2.5h before #7750 (SGPR release for wave-separated TDM)
landed in `KernelWriterAssembly.py`, then merged ~3 days later without re-test — producing a
gfx1250 compile fault on develop that neither PR's own CI could have seen. That is exactly the
stale-base-on-high-coupling-file case the pre-merge gate flags as **mandatory rebase + re-run**.

PR #7781 added gfx950 MXFP8 YAML fixtures carrying dead `MergeFiles` / `DeviceLDS` keys, while #8714
removed those keys from the `GlobalParameters` allow-list. The two PRs shared **no file**, so both
went green; once both were on `develop` the strict-corpus unit test
(`test_input_yaml_corpus_is_strict_clean`) rejected the fixtures, and the break only surfaced
downstream in the ROCm/TheRock rocm-libraries bump (TheRock #6133, tracked by #8810). That is the
validator-vs-validated-data collision the no-file-overlap gate above is designed to catch.

PR #10003 added a gate that turned off write-after-read hazard tracking in stinkytofu for every
non-sparse gfx1250 kernel. Its rationale was one line ("Disable for non-sparse kernel"), its test
evidence was "ctest" and "tox", its unit test asserted on `Solution.py`'s source text, and the
existing hazard FileCheck test was edited to pass the new flag. About one launch in 2,000 then read a
matrix operand after it had been overwritten, the root cause of four P1 silent-data-corruption defects
on gfx1250 (ROCM-31905, ROCM-31901, ROCM-31918, ROCM-32099), fixed by #12170. The `hazard-safety` class,
the M2 tightening and the source-text smell above each block it. For the opposite, PR #11153 is a
model `hazard-safety` PR: a hardware reproducer (12 of 30 runs failing before the fix, 0 of 30 after),
tests shown to fail with the fix reverted, and a stated risk level.

