[Skills] Fix silently-ignored frontmatter, de-drift kernel skills and CLAUDE.md

[jhinpan]

Audit of all 16 skills in .claude/skills/, verified against the source at
e3380676. No skill was removed — each has a distinct job — but several had
drifted far enough to be actively misleading.

Broken as written

Frontmatter that Claude Code silently ignores. capture-kernel-trace,
kernel-trace-analysis, and lds-optimization declared tools:, which is not
a recognized SKILL.md field — the field is allowed-tools:. Their tool
pre-approval has never applied. kernel-trace-analysis also carried a note:
key holding a real constraint ("analysis is programmatic, do NOT use GUI
tools") that consequently never reached the model. format-code declared no
allowed-tools at all.

Worse, build-rocm-image's description was an unquoted one-line scalar
containing Usage: /build-rocm-image; the embedded : makes the YAML
invalid, and invalid frontmatter is dropped wholesale — taking
allowed-tools: Bash and the declared name/description with it.

All 16 skills now parse as YAML and expose only recognized keys.

A skeleton that cannot run. flydsl-tile-programming Pattern D opened with
from flydsl.expr import buffer_ops. #880 moved that module to
kernels/common/buffer_ops.py, so the skeleton raises ImportError. Replaced
with the make_buffer_tensor + fx.copy view; the raw intrinsics remain
documented as an escape hatch at their real path.

Wrong architecture. The same skill labelled s_wait_loadcnt /
s_wait_storecnt / s_wait_dscnt as "CDNA4 / gfx950". These are gfx12+
(gfx1250 / RDNA4) — in-tree they appear only in gfx1250 and rdna3 kernels, and
kernels/gemm/rdna3_f16_gemm.py:304 says so directly. Following that guidance
on gfx950 does not work.

A TV layout that is not equivalent. Both the wizard and the reference built
a TiledCopy TV layout from a bare raked_product. make_layout_tv also
derives the mapping via composition(right_inverse(layout_mn), ...) — see
examples/02-tiledCopy.py. Both now use make_layout_tv.

Invalid sample. flydsl-kernel-authoring's element-wise template had two
body lines flush-left, so it was not valid Python. Its Abs recipe also dropped
the Vec(...) wrap every sibling recipe uses.

Dead cross-reference. That skill pointed twice at a
flydsl-kernel-code-cleanup skill; the skill is named kernel-code-cleanup.

Self-contradiction

prefetch-data-load documents the gfx942 combined 512-entry arch_vgpr + accum_vgpr model and states ">512 → SPILL", then tells the reader to keep
arch_vgpr + prefetch_vgprs <= 256 "to avoid spills". 256 is the 2-wave
occupancy boundary, not the spill threshold.

More broadly, the authoring/debug/perf skills still taught buffer_ops,
ArithValue, raw rocdl.mfma_*, and copy_atom_call as current, while
kernel-code-cleanup (the newest skill) exists specifically to migrate code
off them. That is now reconciled: copy_atom_call → fx.copy at single-atom
sites per cleanup §7b, ArithValue dropped from recommended-type lists, and
the deprecated spellings that remain in transcribed examples are labelled as
such with a pointer to kernel-code-cleanup.

Also: debug-flydsl-kernel used the deprecated rocm-smi (now amd-smi), and
the expr/rocdl module list was missing cdna3, cdna5, rdna3, rdna4.

One developer's environment in shared skills

flydsl-kernel-authoring §12 ran every example through
ssh hjbog-srdc-39.amd.com 'docker exec hungry_dijkstra ...';
kernel-trace-analysis began with cp ~/Documents/input.yaml;
capture-kernel-trace told the agent to read a MEMORY.md that does not exist
in this repo. All three now show the local path first and parameterise or ask
for the remote one.

Smaller items

• format-code documented only the Python CI gate; pre-checks.yaml also runs
  cpp-style via .github/scripts/check_cpp_style.sh. Documented, including
  that it checks rather than rewrites and that BASE_SHA must be set locally
  or it falls back to HEAD^.
• gemm-optimization §3/§4 restate lds-optimization and prefetch-data-load
  in GEMM-specific form with no link either way. Cross-references added — the
  split itself is deliberate and left intact.
• rocprof-trace-decoder was pinned at 0.1.6 in one skill and 0.1.5 in
  another; the version-matching rule is now stated instead.
• add-target-atom-op's description was 1199 chars, the longest of the 16 and
  always resident in the skill listing. Trimmed to the routing signal; the
  design detail it duplicated is already the skill body (§1.1–1.3). Listing
  cost drops from ~2180 to ~1820 est. tokens.

Deliberately not changed

• lds-optimization padding math needs an author's eye. It argues that
  padding one fp16 element gives "129 * 2 / 4 = 64.5 → fractional → conflicts
  eliminated". One fp16 is 2 bytes — half a 4-byte bank — so the shift only
  produces a 2-row period rather than eliminating conflicts, and the companion
  formula padding_elements = 32 / element_size_bytes looks inverted. I did
  not rewrite a hardware claim I cannot measure here; flagging for review.
• fx.thread_idx.x vs gpu.thread_id("x"). flydsl-kernel-authoring
  calls the former legacy, but it is the dominant spelling in kernels/ (38
  uses vs 8). Both are exported; churning the skeletons would make them less
  representative than the tree.
• capture-kernel-trace / kernel-trace-analysis overlap. The latter's
  "Mode B" duplicates the former's collection steps nearly verbatim, down to
  the att_* values. Consolidating changes how both are invoked, so it is left
  for a separate decision.

Verification

• All 16 SKILL.md frontmatter blocks parse as YAML with only recognized keys,
  and every name matches its directory.
• Every python fence in the edited skills re-checked for indentation errors;
  the only real one is fixed (remaining hits are markdown list sub-blocks and a
  multi-line formula).
• Every repo path, script, doc, and symbol referenced by the edited text was
  confirmed to exist at e3380676.
• scripts/check_python_style.sh: no Python files changed.
• Documentation only — no library, kernel, or build code is touched.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[jhinpan]

Update: self-review pass + CLAUDE.md

Ran a full review over this branch before asking for eyes. It found 15 issues, all
verified against the source — including two places where my own edits were worse
than the text they replaced. Fixed in 77a7dae5, plus a scope extension in b5fdcda0.

Reverted — my rewrites broke working text

• flydsl-tile-programming Pattern D. The make_buffer_tensor template I
  substituted was not runnable: it dropped bid (so every workgroup reads the same
  tile), and fx.slice(tA, (None, tid)) on an (M,N) view yields an M-element strided
  column feeding a 4-element rmem tensor, under a # after partitioning tA comment for
  a step the snippet never performs. Restored the original working snippet; fixed only
  its real defect, the dead flydsl.expr import path.
• lds-optimization write-read-distance example. Converting the loads to fx.copy
  introduced six undefined names, stranded next_offsets as dead, and dropped the
  bindings the surrounding prose refers to. Restored and labelled schematic.

Wrong as written

• s_waitcnt(vmcnt=0, lgkmcnt=0) was commented "everything". An unset counter maps to
  its maximum, which the hardware reads as already satisfied, so expcnt was never
  waited on — weaker than the s_waitcnt(0) it replaced.
• The keyword s_waitcnt form is not universal: universal.py dispatches
  gfx942/gfx950/gfx11xx/gfx120x and raises ValueError otherwise, so it fails on
  gfx1250 — whose escape hatch the previous commit had deleted. Restored.
• amd-smi reset -g <idx> is not a reset; -g only selects the device. Now -G -g.
• I claimed build-rocm-image selects the decoder release automatically. It hardcodes
  RTD_VERSION="0.1.5".
• fx.Vector is class Vector(ArithValue), so "use fx.Vector, not the deprecated
  ArithValue" was self-contradictory.
• Chasing a dtype=T.i32 finding surfaced a pre-existing bug: Types members are
  @property, so Pattern D's fx.T.f32() was calling an ir.Type.

Carried defects in text this branch touched

• kernel-trace-analysis ships hotspot_analyzer.py and pmc_l2_analyzer.py in its
  scripts/ dir, but told the agent to hand-write the first into /tmp and ran the
  second from a repo-root scripts/ containing neither. Both now use
  ${CLAUDE_SKILL_DIR}.
• format-code's C++ block inherited the false-pass its Python half warns about: the
  wrapper diffs committed revisions, so uncommitted edits exit 0 locally then fail CI.
• flydsl-kernel-authoring listed a kernels/mma/ package that does not exist.

Scope extension: CLAUDE.md (b5fdcda0)

The sharpest finding was that de-drifting only the skills left the job half done —
CLAUDE.md is loaded every turn while skills load on demand, and it still said
"Prefer ... fx.copy_atom_call", recreating the exact contradiction this PR set out to
remove. Worse, all 10 paths in its Helper-placement rule resolved to nothing after
the kernels/ subpackage reorg — and that rule tells you to search for and reuse an
existing helper rather than duplicate one, so unresolvable paths actively cause the
duplication it forbids. Every kernels/, python/, docs/, tests/, lib/ path in
CLAUDE.md now resolves.

Still open

docs/ (quickstart.rst, kernel_authoring_guide.md, cute_layout_algebra_guide.md,
architecture_guide.md) still teaches copy_atom_call and the bare raked_product TV
layout, and publishes to the public site. Left for a separate PR to keep this one
reviewable. The lds-optimization padding question from the description is also still
open for someone who can measure it.

Worth noting: nothing in tests/, scripts/, or .github/workflows/ lints doc or
skill prose against the Python API (check_typed_arithmetic_usage.py scans .py only),
so this whole drift class recurs undetected.

[jhinpan]

Second review pass (6bff1e67)

A second review over the whole branch found 15 more issues, all verified against the
source tree. Roughly two-thirds were defects this branch introduced, including in the
commit that fixed the first review — so the earlier "fixed" state was not clean.

Methodology correction first: an earlier runtime check in this branch was run against
the installed wheel in /opt/venv, which is stale — it still ships expr/vector.py and
expr/buffer_ops.py, both long gone from the source tree. Everything in this pass is
verified against python/flydsl/ directly.

Symbols that never existed

• All three names in flydsl-kernel-authoring's MFMA reference were wrong:
  mfma_f32_16x16x16_f16 → mfma_f32_16x16x16f16, mfma_f32_16x16x32_fp8 →
  mfma_f32_16x16x32_fp8_fp8, mfma_i32_16x16x32i8 → mfma_i32_16x16x32_i8. The
  signature is (result_type, operands), not (a, b, acc). The atom form now leads.
  The phantom name appeared four more times in prefetch-data-load — underneath an "API
  note" this branch added that described the examples as current, which blessed
  unrunnable code. Converted to fx.gemm.
• fx.rocdl.advance_tdm_atom exists nowhere. cdna5.py documents the K-loop bump as the
  imm_offset atom-state kwarg — and only fx.copy forwards kwargs
  (primitive.py:1109 set_value; copy_atom_call takes none), so the TDM example
  needed both fixes to be coherent.
• CLAUDE.md's target-neutral rule listed a vector module that does not exist and omitted
  enum, which does and is star-imported.

Bad advice this branch introduced

The gfx1250 fallback added in 77a7dae5 told readers to use a raw positional s_waitcnt
bitfield. universal.py passes it through unvalidated, but the layout is arch-specific —
cdna3 packs lgkmcnt<<8 | expcnt<<4, rdna3 packs vmcnt<<10 | lgkmcnt<<4 | expcnt — so
the same literal is not the same wait, and the dispatcher refuses gfx1250 precisely
because its encoding is unknown there. The block also contradicted itself three lines
later. It now points at the split counters, which is what every in-tree gfx1250 kernel
uses. The same comment conflated gfx1250 with RDNA4; "gfx1250".startswith("gfx120") is
False and they dispatch differently.

Also PYTHONPATH=./ python3 my_kernel.py only works under pip install -e .; restored
the build-fly/python_packages + LD_LIBRARY_PATH form from CLAUDE.md:102.

Half-applied edits

Four places where an earlier commit here fixed one occurrence and left its twin:
kernel-trace-analysis Step 4 kept "Write the script (see above)"; format-code's "Check
only" was retitled for C++ but held only the Python command; CLAUDE.md's layout tree kept
the old expr/rocdl list corrected 147 lines below it; and a wrapped hyphen rendered as
"the register -budget rules".

To stop relying on eyeballs for this, the branch is now checked mechanically: all 86
fx.* symbols and every rocdl.* symbol in the skills resolve against
python/flydsl/expr/, all 16 frontmatter blocks parse with only recognized keys, and
every repo path in CLAUDE.md resolves.

Flagged, deliberately not resolved

gemm-optimization §10.2 teaches a separate 256+256 VGPR model and says the files "do not
compete"; prefetch-data-load and lds-optimization teach a combined 512-entry budget
and call the separate model gfx908/CDNA1-only. They give opposite answers on wave count
and on whether a prefetch buffer is safe. Marked inline as unresolved rather than picking
a winner on a hardware claim that cannot be measured from here — same treatment as the
lds-optimization padding question. Both need an owner with hardware access.

[jhinpan]

Both hardware questions are now settled by measurement (865fcd1f)

I had flagged two claims as needing "an owner with hardware access". That was wrong — this
node is 8× MI355X (gfx950), the exact architecture both claims concern. Measured on HIP
device 3 (amd-smi 1, 0000:15:00.0), held under flock /tmp/gpu-3.lock, selected by
pick-idle-gpu.py --samples 10 (0% peak util, 0.3 GiB used).

1. VGPR occupancy — gemm-optimization §10.2 was wrong

It taught two separate 256-entry files that "do not compete", contradicting
prefetch-data-load and lds-optimization. The combined-512 model is correct for
gfx90a+.

LLVM encodes the rule directly — getTotalNumVGPRs(has90AInsts, NumAGPR, NumVGPR) in
llvm/lib/Target/AMDGPU/Utils/AMDGPUBaseInfo.cpp returns alignTo(NumVGPR, 4) + NumAGPR
when the target has GFX90AInsts (gfx90a, gfx942, gfx950 all do), and
max(NumVGPR, NumAGPR) otherwise.

Confirmed on this gfx950 with hipcc -Rpass-analysis=kernel-resource-usage across 13 MFMA
kernels of increasing accumulator count. The combined model reproduces the compiler's own
reported occupancy 13/13; the separate-file model misses two and under-predicts both:

arch	accum	reported occ	combined	separate
36	32	7	7 ✅	6 ❌
84	80	3	3 ✅	2 ❌

Spilling first appears at arch=256/accum=256 — combined 512 exhausted — not when either
file alone passes 256 (arch=228/accum=224 does not spill).

2. LDS padding — the skill's advice was right, my doubt was wrong, its formula is harmful

The PR description questioned "pad 1 fp16 element eliminates conflicts" because 2 bytes is
half a bank. That reasoning was wrong. The bank index is
(t * row_stride_bytes / 4) % NBANKS, so an odd number of 2-byte elements gives a
fractional-dword stride that walks all 64 banks. The skill's conclusion was correct; only
its wording was loose. Now derived properly via gcd(row_stride_dwords, NBANKS).

What is wrong is the sizing formula. padding_elements = bank_count / element_size_bytes
gives +32 elements for fp16 on gfx950 → 80-dword stride → gcd(80,64)=16 → 16-way
conflict. Measured (one wavefront, strided column read of a [64][64+PAD] fp16 tile,
best of 9 × 50 launches):

PAD	row stride	predicted	measured	vs best
0	128 B (32.0 dw)	32-way	7.11 ms	+59%
1	130 B (32.5 dw)	1-way	4.61 ms	+3%
2	132 B (33.0 dw)	1-way	4.48 ms	best
4	136 B (34.0 dw)	2-way	4.62 ms	+3%
32	192 B (48.0 dw)	16-way	5.81 ms	+30%

The formula the skill recommended is 26% slower than the +1 it also recommended.
Replaced with the gcd rule, the measured table, and an explicit "more padding is not safer"
warning — pad 4 already costs a 2-way conflict.

Benchmark limits stated in the skill: latency-bound on a single wavefront, so absolute
ratios are compressed relative to the conflict factor, and it cannot separate 1-way from
2-way. It establishes the ordering, not an expected speedup.

All three skills now agree on the VGPR model, and the inline "unresolved" flag is removed.
Nothing in this PR is left flagged for someone else to measure.

[jhinpan]

Enforcement: scripts/check_docs_api.py (9137f26c)

Everything this PR fixes drifted silently for months because nothing in CI reads
CLAUDE.md or .claude/skills/ — check_typed_arithmetic_usage.py scans .py only.
These files are executed by agents, so a stale symbol or an unresolvable path is a defect
with the blast radius of broken code, yet the only thing catching them was careful reading.

The new gate checks four mechanical properties, statically, without importing FlyDSL:

1. fx.<name> / rocdl.<name> symbols resolve
2. repo-relative paths in backticks exist
3. skill frontmatter parses as YAML, uses only recognized keys, and name matches its directory
4. **<name>** skill cross-references point at a skill that exists

The symbol universe is what python/flydsl/expr/ defines ∪ what kernels/, tests/ and
examples/ actually call. The second half is load-bearing: fx.rocdl re-exports the
upstream MLIR ROCDL dialect with import *, so ops like s_wait_dscnt have no in-tree
definition and are recognizable only because real kernels call them. Two upstream ops
nothing calls yet are allowlisted with provenance.

Only Python fences and prose are scanned — MLIR, TableGen, C++ and shell blocks legitimately
spell ops as rocdl.mfma.f32.... Genuine placeholders opt out with a trailing
<!-- api-check: ignore -->, used exactly twice (the deliberately hypothetical CDNA5
subtarget, and python/flydsl/_mlir/, absent until you build).

It has teeth

Run against origin/main it reports 25 problems — 23 of them defects this PR had to find
by hand across three review rounds:

CLAUDE.md:196: path does not exist: kernels/kernels_common.py
build-rocm-image/SKILL.md: frontmatter is not valid YAML (mapping values are not allowed here)
capture-kernel-trace/SKILL.md: unrecognized frontmatter key `tools` (silently ignored at load)
kernel-trace-analysis/SKILL.md: unrecognized frontmatter key `note` (silently ignored at load)
flydsl-kernel-authoring/SKILL.md:673: unknown symbol `mfma_f32_16x16x16_f16`
flydsl-kernel-authoring/SKILL.md:619: unknown symbol `advance_tdm_atom`
flydsl-kernel-authoring/SKILL.md:235: no such skill: flydsl-kernel-code-cleanup
flydsl-kernel-authoring/SKILL.md:57:  path does not exist: python/flydsl/expr/buffer_ops.py
kernel-trace-analysis/SKILL.md:31:   path does not exist: scripts/hotspot_analyzer.py
prefetch-data-load/SKILL.md:91:      unknown symbol `mfma_f32_16x16x16_f16`
...

The remaining two are the annotated exceptions.

What it deliberately cannot do

It is mechanical. It would not have caught the other three classes this PR fixes: the
wrong s_wait_* architecture attribution, the contradictory VGPR occupancy model, or the
harmful LDS padding formula. Those still need review and, as it turned out, measurement.

docs/ is out of scope until its own drift is cleared (the remaining open item);
--include-docs enables it, and should be turned on in the PR that fixes those files.

[jhinpan]

/rerun-ci