SuperTensor/SKILL.md

---
name: supertensor
description: Create or refine clean, shape-aware figures for tensor/matrix/vector formulas or tensor code — matrix-block diagrams, entry heatmaps, row/column shard stripes, stacked 3D/4D tensors, attention, tensor/expert parallelism, broadcasting, reductions, contractions, gather/scatter and routing. Use whenever tensor shapes or axis meanings must be visually aligned with the computation, or the user runs $supertensor. Not for plotting numeric data (loss curves, benchmark bars, scatter plots), architecture block diagrams without shapes (use superfig), stepwise rewrite figures (use superderive), or full paper notes (use superpaper).
---

# supertensor

Turn a formula or a tensor-code path into one dense, slide-ready figure with three zones:

1. **Top — formula.** The clean mathematical definition. No shape underbraces.
2. **Middle — computation.** Colored faces, shards, stacks, operators, collectives.
3. **Bottom — meaning.** Axes, object semantics, mechanism. One box, three rows.

The `assets/supertensor.sty` package enforces most of the geometry and style rules
by construction. **Draw with the package; do not hand-roll `\draw` rectangles.**
A figure built from raw TikZ has to re-earn every invariant by hand and usually fails one.

## Workflow

1. **Preflight.** `./scripts/preflight.sh`. Exit 0 = TikZ+CJK path. Exit 1 = degraded
   (say so in the delivery). Exit 2 = no LaTeX; read `references/fallback.md` before
   falling back and state explicitly which package guarantees are unavailable.
2. **Reduce** the input to one primary computation path. Drop equivalent objectives,
   diagnostics, and secondary metrics unless asked for.
3. **Build two ledgers** before drawing anything:
   - *shape & semantics* — per symbol: semantic kind, dtype/domain, global and local
     shape, axis meanings, producer/consumer, contracted/broadcast/reduced axes.
     See `references/semantics.md`.
   - *geometry* — one `\stdim{axis}{cells}` per symbolic axis, one `\stsetrole{role}{color}`
     per tensor role. Declaring these makes the invariants automatic.
     See `references/geometry.md`.
4. **Pick the smallest grammar** that exposes the mechanism (see below), then draw with the
   flow layout — `\ststage` / `\strow` … `\strowend`, empty coordinate arguments, gaps
   declared once. Reach for an absolute coordinate only when no band can express the
   placement. See `references/api.md` and `references/layout.md`.
5. **Build and audit.** `./scripts/build.sh fig.tex` runs the source linter, TeX checks and
   exports. Then run the remaining visual/semantic audit in `references/checklist.md`
   against the PNG at full size and thumbnail size. Redraw on any mandatory violation.

For code input, trace the concrete `matmul`, `einsum`, `reshape/view`, `transpose/permute`,
concat, broadcast, and collective calls. Keep code variable names where useful; state any
shape or convention you inferred.

## Choose the visual grammar

| Fact to expose | Grammar | Package |
|---|---|---|
| mask, sparsity, causal structure, elementwise roles | entry cells | `\stface[pattern=causal/lower/band/diag/data]` |
| sharding, device ownership, channel groups | adjacent faces tiling a parent | two `\stface` calls, one role each |
| leading axes (`B`, `h`) | depth | `\ststack{...}{sheets}` |
| discrete choices (indices, token ids, expert ids) | symbols in cells, no ramp | `\stindexface` |
| data movement, collectives, non-linear ops | arrows and nodes | `\stlink`, `\stcomm` |
| a split along the contracted axis | a vertical pair inside one band slot | `\stcol` … `\stcolend` |
| adjacent objects that are one composite (heads of `q`, shards of `W`) | an outline in their own role hue | `\stgroup` … `\stgroupend` |
| an aside about a whole band | a side card off its right edge, one per figure | `\stcallout` |

Combine grammars only when each one adds information. Known zeros stay unfilled; masks,
diagonals, sparsity and partitions must encode their exact structure.

## Non-negotiables

These are the rules that make the figure *true* rather than merely pretty. Each has a
reference file with the full statement and the failure it prevents.

- **Geometry** (`references/geometry.md`) — one symbolic axis, one physical edge length,
  everywhere. `a×a` is a square. A transpose swaps the face, not the label. Both
  occurrences of a contracted `k` are the same length. Shards tile their parent exactly.
- **Semantics** (`references/semantics.md`) — one block, one semantic object. Scores,
  indices and masks are three different grammars, never one heatmap. Close the chain
  from continuous score to discrete index to gathered value.
- **Layout** (`references/layout.md`) — everything is a bounding box; tangency counts as
  collision. Reserved lanes for stage heading / tensors / symbols / shapes. Connectors on
  the background layer, text on the foreground layer. Place by cursor, not by hand-tuned
  coordinate: a magic-number offset is only valid for the content it was tuned against.
- **Style** (`references/style.md`) — muted palette, one hue per role, ≤4 active hues per
  row plus gray, three separated lightness levels, non-periodic texture, no decoration.

`references/antipatterns.md` shows what each violation looks like in a rendered figure —
read it once before your first figure.

## Output

Default to editable TikZ. `scripts/build.sh` emits PDF, SVG, white-background PNG,
transparent PNG and a thumbnail. Deliver: the PNG preview, a short mechanism explanation,
and the `.tex` source plus vector artifact.

- **Chinese figures:** `\usepackage[cjk]{supertensor}` (XeLaTeX + portable Fandol). Do not
  select an OS-specific CJK font unless the user asks and accepts the portability cost.
- **English figures:** `\usepackage[en]{supertensor}` — same geometry, English rail labels.
- Keep math in LaTeX, not raw Unicode.
- Add `\stsignature{<subject>}{<box>}` only when the user or house template asks for an
  identification line. It renders only the subject, with no author or handle.

## Iterating

When the user asks for a change, do not restart the figure. Edit the ledger or the one
call that owns the offending object, rebuild, and re-audit. If a fix requires shrinking
type, closing the gutter, or covering another object, the layout is wrong — move the stage
to another row instead. Ask before dropping a stage or an object the user named.