Tikz

TikZ Collision Audit

Purpose: Find and fix residual visual collisions in TikZ figures in a given .tex file. Labels on arrows, text inside boxes, arrows crossing arrows — this skill catches them using measurement, not intuition.

The fundamental rule: an AI agent cannot reliably eyeball where TikZ elements land. All placement must be verified mathematically before declaring it safe.

Critical context: this is a repair tool, not the primary defense

tikz runs after TikZ has been generated. It audits existing code and fixes what it finds. But it cannot reliably fix diagrams that were never built with measurement in mind.

The upstream defense is writing TikZ safely from the start:

1. Every \node declares explicit minimum width and minimum height
2. Every edge label carries a directional keyword (above, below, etc.)
3. A coordinate map comment block precedes every tikzpicture
4. Standard diagram types use canonical safe templates
5. scale is never used on complex diagrams

When new decks are authored via beamer-deck, prefer applying these rules during generation. tikz is the downstream cleanup pass for anything that slipped through or for legacy/hand-written TikZ.

When upstream rules were applied: tikz should find few or no issues. Run it as a check.

When upstream rules were NOT applied (legacy TikZ, hand-written diagrams, inherited decks): tikz does its best, but expect more findings, more iteration, and lower reliability on autosized nodes and scaled diagrams.

The companion reference tikz_rules.md (in this skill's directory) contains the full formulas and worked examples — read it once before running the audit passes below.

Step 1: Identify the file and run the pre-check

If the user specified a file, use it. If not, ask. Then:

grep -n "tikzpicture\|begin{frame}\|node\|draw\|bend\|foreach" [file].tex | head -100

Get a sense of scope: how many TikZ diagrams, how many frames, how many arrows.

Pre-check: were the generation rules followed?

Before running the six audit passes, quickly assess whether the TikZ was written safely:

# Check for autosized nodes (no minimum width/height)
grep -n "\\\\node" [file].tex | grep -v "minimum"

# Check for scale on tikzpicture
grep -n "scale=" [file].tex

# Check for coordinate map comments
grep -n "% Coordinate map\|% Node map\|% Layout" [file].tex

If autosized nodes are widespread: warn that repair reliability will be lower. The fix is upstream — add explicit dimensions to every node. Consider doing that first before running the audit passes.

If scale is used on a complex diagram: warn that coordinates are compressed but text is not. Gap calculations in Passes 2–5 must compensate for the scale factor, but this compensation is fragile. The better fix is upstream: redesign at intended size.

If no coordinate map exists: the audit will take longer because spatial relationships must be reverse-engineered from the code rather than read from a plan.

Step 2: For each TikZ diagram, run all 6 Passes in order

Full rules and formulas are in tikz_rules.md alongside this SKILL. Read it if you haven't. What follows is the operational checklist — the reference file has the formulas and worked examples.

Pass 0: Cross-slide consistency

grep -n "node.*{" [file].tex | grep -v "^[[:space:]]*%"

If the same diagram appears on multiple slides: colors, positions, and font sizes must be identical across all instances. Only the deliberate change (a new highlight, a new node) should differ.

Pass 1: Bézier curves — do this FIRST

grep -n "bend" [file].tex

For each curved arrow found, compute:

chord_length = distance between the two endpoints
max_depth    = (chord_length / 2) × tan(bend_angle / 2)
safe_zone    = max_depth + 0.5cm

Quick reference:

Check 1: Is any label within safe_zone of the baseline, in the direction the curve bends? If yes → move the label.

Check 2: Does the curve cross any other arrow in the same figure? Curves bending down cross vertical arrows. Fix: reverse the bend direction.

Pass 2: Label-between-nodes gap calculation

For every arrow label placed between two nodes:

Available gap  = center-to-center distance − half-width(A) − half-width(B)
Usable space   = Available gap − 0.6cm   [0.3cm padding each side]

Estimate label width using character counts:

Known limitation: these estimates break down for math mode ($\beta$ is wider than 1 character), \textbf content, multi-word labels, and anything non-ASCII. When in doubt, overestimate width by 20%.

If scale is in effect: multiply the usable space by the scale factor, but leave the label width estimate at native size. This is the core of the scale problem — coordinates shrink, text does not.

If estimated label width > usable space: guaranteed collision. Fix: move above/below, or shorten text, or increase node spacing.

The most common fix for labels that exceed the gap: break the label out as a standalone \node positioned above the arrow midpoint — clear of both boxes — rather than as an inline edge label.

Pass 3: Arrow label positioning keywords

grep -n "node\[" [file].tex | grep -v "above\|below\|left\|right\|anchor\|pos\|midway\|near"

Every arrow label must carry a directional keyword. Any node[...] on an arrow without above, below, left, right, anchor=, pos=, or midway will sit ON the arrow line. Fix: add the keyword.

Pass 4: Labels vs. drawn shapes (Boundary Rule)

For every \node, \fill, \draw circle/rectangle: compute the boundary. Any text within 0.4cm of a shape edge is a collision.

Circles: center (cx, cy), radius r → boundary from cy − r to cy + r Rectangles/boxes: bottom-left (x,y), width w, height h → top edge at y + h

If a label coordinate puts it inside or touching a shape boundary — move it 0.4cm outside.

Note on scale: scale=0.8 shrinks coordinates but NOT text. A 2 cm gap becomes 1.6 cm, but a \small label stays \small. Recalculate all gaps accounting for scale. If the diagram uses scale on a complex figure, flag this to the user as an upstream problem — the reliable fix is to redesign at intended size, not to compensate in the audit.

Pass 5: Margin check

Minimum clearances:

Also check:

• Multi-line nodes have align=center or align=left?
• No node text clipped by the slide margin?
• If scale is used: did text get unintentionally large relative to shrunken coordinates?