Superfig/SKILL.md

---
name: superfig
description: Create or refine clean paper-style figures for non-tensor concepts — architecture and block diagrams, pipelines and data flow, state/time flows, dependency graphs, and conceptual mechanism diagrams. Use whenever a paper idea should be explained with clear nodes, edges, grouping, captions, and a short meaning box in a muted slide-ready style, or the user runs $superfig. Not for tensor/matrix/shape semantics (use supertensor), stepwise rewrite figures (use superderive), full paper notes (use superpaper), or plotting numeric data.
---

# superfig

Turn one paper claim or mechanism into one dense, slide-ready figure with three zones:

1. **Top — idea.** The compact claim or formula. Optional; call it after the drawing.
2. **Middle — structure.** Semantic nodes, directed edges, grouped composites, and captions.
3. **Bottom — meaning.** What the idea is, what the objects are, what the mechanism does.

`assets/superfig.sty` enforces the house style and the common cursor/role discipline.
Draw with `\sfnode` / `\sfconn` / `\sfarrow` / `\sfgroup`; do not hand-roll TikZ rectangles
and arrows unless the linter explicitly allows it.

## When to use

- Architecture, block diagram, pipeline, data flow, dependency graph, state or time flow.
- A conceptual mechanism that is not a tensor shape: nodes, arrows, containment, lanes.
- A figure that should look like `supertensor` in palette and text hierarchy.

Do **not** use for tensor faces, axes, contractions, sharding or broadcasting; route those to
`supertensor`. Do not use for loss curves, benchmark bars, scatter plots, or dashboards.

## Workflow

1. **Preflight.** `./scripts/preflight.sh`. Exit 0 = TikZ+CJK path. Exit 1 = degraded
   (say so). Exit 2 = no LaTeX; read `references/fallback.md` and name the lost guarantees.
2. **Reduce** the paper to one primary claim. Drop parallel objectives, optional modules,
   diagnostics and secondary paths unless the user asks for them.
3. **Build a semantics ledger** before drawing:
   - *nodes* — each block is one semantic object: kind, domain/range, owner, lifecycle.
   - *edges* — each arrow is data flow, control flow, dependency, or causality; never decoration.
   - *groups* — an outline only when it names a real composite object.
   See `references/grammar.md`.
4. **Choose the smallest grammar** that exposes the mechanism:
   - one object = `\sfnode[role=..., level=...]{name}{label}{width}{height}`
   - horizontal flow = `\sfstage` + `\sfrow` … `\sfrowend`
   - horizontal connector with label = `\sfconn{name}{label}`
   - fixed/branching edge = `\sfarrow[options]{from}{to}` or `\sfarrowlabel`
   - composite = `\sfgroup[role=...]{name}{(member1)(member2)}{}` then `\sfcaption`
   - a whole-band aside = `\sfcallout`
   - bottom explanation = `\sfmeaningbox`
   Full macro list: `references/api.md`. Worked figures: `examples/`.
5. **Build and audit.** `./scripts/build.sh fig.tex` runs lint, TeX checks, and exports.
   Then run `references/checklist.md` against the PNG full-size and thumbnail. Redraw on
   any mandatory violation.

## Non-negotiables

- **Semantics** — one node, one object. An edge says one relationship. A group is a real
  composite, not a decorative border.
- **Layout** — use the cursor in flow rows; use `at={<coord>}` only when the topology is
  genuinely non-linear. Never hand-tune a neighbor against a magic offset.
- **Style** — muted palette, one hue per role, at most four active hues plus gray,
  three separated lightness levels, no saturated primaries, no dashboard clutter.
- **Build** — `Missing character`, overfull/underfull boxes, and `Package superfig Warning`
  are build failures, not cosmetic warnings.

`references/antipatterns.md` shows the common ways a clean compile still tells the reader
something false.

## Output

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

- **Chinese figures:** `\usepackage[cjk]{superfig}` (XeLaTeX + portable Fandol). Keep
  standard English terms where natural (`softmax`, `logits`, `gather`).
- **English figures:** `\usepackage[en]{superfig}` — same geometry, English meaning-box rails.
- Keep math in LaTeX, not raw Unicode.
- Add `\sfsignature{<subject>}{<box>}` only when the user or house template asks for it.

## Iterating

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