SuperTensor/SKILL.md

name, description

name

description

supertensor

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.