/new-diagram¶
figuresMITpaper-drafting
Create a New TikZ Diagram¶
Scaffold a diagram from templates/tikz-snippets/, check it against the prevention rules, compile standalone, run the reviewer with measurement citations, and loop until the diagram passes. Use this instead of writing TikZ from scratch; the snippets embed the invariants that tikz-prevention.md requires.
Inputs¶
$0(optional) — snippet name (without.tex). One of the filenames intemplates/tikz-snippets/. If omitted, list the gallery and ask the user to pick.$1(optional) — output path. Defaults toFigures/new_diagram.tex— ask the user if this target exists so we don't clobber.
Workflow¶
Step 1: Pick a snippet¶
Current gallery (see templates/tikz-snippets/README.md for descriptions):
dag-basic— 3-node causal DAG (X → Y with confounder U)dag-mediation— X → M → Y with direct pathdid-two-period— two-period difference-in-differencesevent-study— event-time coefficients with 95% CIstimeline— horizontal timeline with staggered eventsregression-scatter— scatter + OLS fit + confidence bandflowchart-3step— vertical flow with decision diamondsupply-demand— supply/demand with shifted demand
If $0 is not one of these, or is omitted, ask the user which to use.
Step 2: Copy the snippet to the output path¶
SRC="templates/tikz-snippets/$0.tex"
DST="${1:-Figures/new_diagram.tex}"
## Confirm before overwriting
if [ -f "$DST" ]; then
echo "Output path already exists: $DST"
# Ask the user whether to overwrite. Do NOT clobber silently.
fi
mkdir -p "$(dirname "$DST")"
cp "$SRC" "$DST"
Step 3: Edit the content to fit the user's intent¶
Ask the user what the diagram should show. Edit $DST with the Edit tool:
- Update the comment block at the top so the intent sentence matches the user's goal.
- Update the coordinate map comment if coordinates change.
- Rename nodes and edit labels. Keep node style (
dag-node,flow-node, etc.) unless the meaning actually changes. - Do not add a bare
scale=Xto the tikzpicture options. Coordinates shrink, text does not — collisions follow. Allowed forms:scale=X, every node/.style={scale=X}orscale=X, transform shape. Seetikz-prevention.mdP3 for the full rule andtikz-visual-quality.mdfor thescale=1.1convention. - Every new edge label must carry a directional keyword (
above,below,left,right,above left, etc.).midwayalone is a path position, not a direction — P4 violation.
Step 4: Prevention pre-check (MANDATORY)¶
Run the same shared Python checker /extract-tikz uses — this is the one tool that enforces both P3 and P4 consistently across the two skills:
- Exit
0→ passed, continue. - Exit
1→ violations (stderr reports line, rule, snippet). Fix$DSTand re-run until zero. - Exit
2→ usage error (missing file etc.).
Do NOT re-implement the grep inline. The Python checker correctly handles multi-line \begin{tikzpicture}[...] options and multi-line \draw ... node {...} spans that a line-oriented grep cannot see.
Step 5: Standalone compile¶
All snippets are \documentclass[border=4pt]{standalone} so they compile without a Beamer frame and without Preambles/header.tex:
cd "$(dirname "$DST")"
xelatex -interaction=nonstopmode "$(basename "$DST")" > /tmp/tikz-compile.log 2>&1
Check exit code and *.pdf file size. If compile fails, read /tmp/tikz-compile.log and fix the .tex source.
Step 6: Visual review via tikz-reviewer¶
Spawn the tikz-reviewer agent with Task (subagent_type=tikz-reviewer). Pass the .tex source and the compiled .pdf path. The reviewer is now required to cite the pass and formula from tikz-measurement.md for every CRITICAL/MAJOR finding — vague reports are rejected.
Loop:
- If
APPROVED→ go to Step 7. - If
NEEDS REVISIONorREJECTED→ apply fixes to$DST, re-run Step 4 (prevention pre-check), re-compile (Step 5), re-invoke reviewer.
Max 5 rounds. If after 5 rounds the reviewer is still reporting CRITICAL issues, surface the situation to the user — the snippet or the requested content may need redesign, not just tweaking.
Step 7: Optional — convert to SVG for Quarto¶
If the user plans to use the diagram in Quarto slides (not just Beamer), convert the compiled PDF to SVG:
Snippet-based diagrams are single-page, so a single .svg with the same basename as .tex is correct here. This differs from /extract-tikz, which produces a multi-page PDF from a Figures/LectureN/extract_tikz.tex master and names outputs tikz_exact_00.svg, tikz_exact_01.svg, ... (0-based filenames over 1-indexed PDF pages). If you need multi-page output for slide-by-slide reveals, use /extract-tikz instead.
Step 8: Clean up build artifacts¶
Leave the .pdf and .svg (if generated). They're what downstream tools use.
Step 9: Report¶
Print a summary:
- Snippet used → output path
- Reviewer verdict and number of rounds
.pdfsize and page count.svgpath if generated- Reminder to
\inputor\includegraphicsthe diagram in the target Beamer/Quarto file
Why start from a snippet?¶
Writing TikZ from scratch reliably produces collisions because the author cannot visually estimate where curves and labels will land. The snippets embed the invariants that tikz-prevention.md requires — coordinate maps, explicit node dimensions, directional edge labels — so the diagram passes the prevention pre-check by construction. You can always deviate from the snippet; the rules still apply.
Cross-references¶
.claude/rules/tikz-prevention.md— the P1–P6 authoring rules..claude/rules/tikz-measurement.md— the six-pass protocol with formulas the reviewer cites..claude/rules/tikz-visual-quality.md— general visual standards..claude/skills/extract-tikz/SKILL.md— for pulling TikZ out of an existing Beamer deck instead of creating new.templates/tikz-snippets/README.md— gallery inventory and adaptation guide.