TheRock/rocm-libraries/projects/hipblaslt/skills/hipblaslt-pr-quality/SKILL.md

---
name: hipblaslt-pr-quality
description: "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/). Adds and tightens base rules; never relaxes a base MUST."
argument-hint: "[author | review | pre-merge] [PR URL | branch:<name> | local]"
extends: rocm-pr-quality
allowed-tools: Bash, Read, Grep, Glob, Task, WebFetch
---

# 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/`).
- 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/**`.
- Tensile / kernel generation: `projects/hipblaslt/tensilelite/**`, especially `KernelWriter*.py`.
- Tests/clients: `projects/hipblaslt/clients/**`.

### 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 — Tensile test levels (maps the base test-level SHOULD to real lanes)
C++ unit → Tensile 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/Tensile/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.

### 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/Tensile/Common/GlobalParameters.py` (the
  global-parameter registry and the `_assertGlobalParametersAreValid` ignored-key allow-list), plus
  the enforcing test `projects/hipblaslt/tensilelite/Tensile/Tests/unit/test_input_yaml_corpus_clean.py`.
- Validated data: YAML fixtures under `projects/hipblaslt/tensilelite/Tensile/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).

### 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.