Convert the system architecture/protocol flow/technical scheme in a paper into high-quality TikZ figures.Goal: high information density + design sense + compiles in one pass. Failure modes: mediocre, loose alignment, coordinates by feel.
Output formatTikZ only（figure.tex，\input embedded in the manuscript) — HTML/CSS/SVG/matplotlib cannot be used as paper structure figure output.
Division of labor with other figure skills (routing by figure type)
| Scenario | Which skill to use | Reason |
|---|---|---|
| Structured figures with a clear design direction: architecture diagrams / flowcharts / pipelines / sequence diagrams / geometric and mathematical illustrations / figures containing formulas | This skill (TikZ) | Vector, native formula rendering, consistent with the body text font |
| Unclear design direction / novel figure type / user wants to see a few directions first | scientific-schematics exploration mode (gpt-image-2 generates 3 direction sketches in parallel, user chooses) |
Divergent exploration is fast; the chosen sketch can be delivered directly, or used as ref.png to return to this skill for replication |
| Illustration-style figures: light/shadow/material/3D/hand-drawn conceptual art, graphical abstract, or the user prefers a polished PNG | scientific-schematics(outputs PNG) |
Raster generators have strong visual expressiveness, and the PNG itself is a qualified deliverable |
| Data charts (experimental result curves/bar charts) | scientific-visualization（matplotlib） |
Data-driven, not hand-drawn structure |
Conventional structure figures default to this skill (vector is the default, not a rule); for those that return to this skill after selecting a sketch via exploration mode, use the replication exemption (see ①.7), using figure-diff.py to compare against ref.png to verify the degree of restoration. Whether the final output is PNG or vector is decided by the user.
Philosophy (must-read before every drawing, above all rules)
The UNFORGETTABLE Question
Before drawing + before delivery, ask yourself:After a reviewer looks for 5 seconds, what do they remember?
- A unique hero substructure?
- An embedded real heatmap / curve / image?
- An information-dense hyperparameters / loss panel?
- A multi-color harmonious zone division?
No "memorable thing" = do not deliver.
Naming the Gravitational Pull (the statistical center you must actively avoid)
The model by default will draw "AI slop academic figures"—below is the mediocre default of the statistical center,actively avoid it：
- ❌ box + arrow only，Zeroembedded data visualization
- ❌ 3-color monotonous palette (common combinations of blue/orange/purple)
- ❌ Single-word labels like "FFN" / "Attention",no formulas / no parameters written
- ❌ Inside the heroonly a box list, no embedded heatmap/curve/micro-figure
- ❌ No information panel (hyperparameters / loss curve / legend / metrics)
- ❌ Flat layoutno visual hierarchy(core and auxiliary have the same weight)
- ❌ Looks "like it was generated by AI in one shot"—no trace of design
Permission for Creativity
Claude is capable of extraordinary academic figure design. Checklist is for catching last-mile bugs,not safe defaults。
You are not practicing drawing structure figures. You are drawing a figure for a NeurIPS / ICML / Nature submission. Reviewers will use this figure to judge the author's domain literacy and level of care. A mediocre box+arrow only figure = desk reject.
Creating space — vocabulary available for the complex tier
For the design vocabulary available in the complex tier (embedded visualization / info panel / embedded math formulas / color scheme / hierarchy / cross-zone / academic polish), see references/step1-instructions.md the section of the same name at the end. Not mandatory, but during the design phaseyou should consider—it is the positive checklist that counters the "statistics-center mediocre default" above.
Visual intuition rules (meta, applied at ④.5 Step 0)
- 0.1-second intuition: visual flow ≠ logical flow = definitely wrong (for each one you write,
\draw, ask whether the reader's intuition is right) - eye trajectory: follow the main line; any place where "stuck" = blocker
- deletion test: whatever can be deleted should be deleted;fixing one bug must not introduce a new aesthetic problem
The most important point
Aesthetics + information density > rule compliance. Rules are only the floor; aesthetics are the ceiling.The 18-item checklist is for catching last-mile bugs—it is not a design guide. The design guide is the Philosophy above.
Complex-tier figure shortcut — TikZ Snippet Library (21 + preview PNGs)
Batch 17 fig153 lesson: the Philosophy text guide let the sub-agent know to embed viz / panel / formulas, butthe visual weight, whitespace, and color coordination still failed—because these are visual perception rather than textual tasks.
Solution：references/tikz-snippets/ provides 21 hand-refined TikZ snippets + 21 PNG previews + a composition rules document.The category list and PNG previews are maintained in only one place, in references/tikz-snippets/README.md 's inline gallery(5 major categories: embedded data visualization / info panel / mathematical geometry / structural flow / whole-figure skeleton elements); do not duplicate them in this file.
Mandatory process for the complex tier：
- First read
references/tikz-snippets/README.md— the inline gallery contains a PNG preview of each snippet - First choice: copy the complete
example-skeleton-B-horizontal.tex(pipeline type) orexample-skeleton-C-centralhero.tex(hero+panels type) as figure.tex, change the content without touching the layout - Second choice(special layout needs): look at the PNGs and choose ≥ 3 snippets to assemble yourself
- Must read
references/tikz-snippets/COMPOSITION-RULES.md— whitespace / alignment / Z-order / whole-figure skeleton between snippets, solving "all the snippets are crammed in but it is still messy" - Must have at the bottom color-legend OR summary-bar
- Never "simplify" the core structure of a snippet — simplification = sparse information = mediocrity
Hard constraints (violation means failure)
🔴 Tool iron rule: use only TikZ; Python/matplotlib substitutes are forbidden(2026-05-22 Batch 17 fig153 lesson: when executing Module-First, the sub-agent used Python+matplotlib to generate .py files = a complete departure from this skill's value proposition):
- The Module-First sub-process (③.A→③.D) must remain TikZ—even if matplotlib is more convenient for drawing embedded viz
- For complex embedded viz , still use native TikZ (
\foreachto draw cells /pgfplotspackage /\drawhand-drawn patch) - Academic paper figure embedding is still the gold standard：
\input{figure.tex}than\includegraphics{fig.png}is superior in formula rendering, vector scaling, and style consistency - only when the userexplicitly requests Python is it allowed — default must be TikZ
🔴 Color rule of thumb: default light background, dark theme requires explicit user request：
- Academic paper standard is white/light bg; dark theme breaks from the body text style
- The Philosophy section's "≥5 zone tones" refers to zone light backgrounds + box medium saturation,notinverting the colors of the entire figure
- sub-agent must not take the liberty of applying a dark theme
⚠️ xelatex + rotate=90 Chinese — renders as unreadable color blocks, all Chinese labels must be horizontal
⚠️ \texttt wrapping Chinese — errors, use only for pure English code \texttt / code_block
⚠️ ctex unavailable — before compiling kpsewhich ctex.sty, otherwise switch to plan B (fontspec)
⚠️ ucharclasses — frequent Missing character for mixed Chinese-English in tikz nodes, forbidden
⚠️ xelatex silently fails on missing fonts — after compiling must grep "Missing character" *.log
⚠️ Single \draw + rounded corners to draw long-distance U-shaped loops — path anomalies, split into 3 independent \draw
Workflow (⓪→⑦)
⓪ 依赖检测 → ① 画图指令（含 ①.7 双候选预览）→ ② 加载规则 → ③ 生成代码 → ④ 编译验证 → ⑤ 评分 → ⑥ 迭代 → ⑦ 沉淀
Degraded path when there is no shell / no write permission
Confirm once before starting whether Bash and Write are available; this confirmation is the entire budget: do not try tools one by one to see them fail, do not dispatch sub-agents to work around it (sub-agents inherit the same set of permissions and hit the same wall), and even less should you copy the error from each attempt into the reply. If either is missing, skip ⓪ dependency detection, ①.7 dual-candidate compilation preview, ④ compilation verification, ④.5 visual feedback loop; ① drawing instructions, ② load rules, ③ generate code still proceed as usual.
The deliverable is the code itself; compilation is only a means of verification. Write the ① design comment block and the complete figure.tex together in the reply, with a closing sentence stating that this session cannot compile, cannot run geometry checks, and cannot do a PNG visual self-review, and asking the user to run xelatex once themselves before coming back. This is the same principle as the Ψ review channel handling "no figure to look at": do what can be done, and name what cannot be done for the user to judge. A figure that is uncompiled but structurally complete can be run as soon as the user pastes it in; a report saying "this session has no shell" is nothing.
⓪ Dependency detection (automatically executed once on first run)
- TeX / pdftoppm / graphviz missing:only prompt the user to install, do not auto-install.
which xelatex || echo "请装 mactex-no-gui (macOS) / texlive-xetex (Linux)"which pdftoppm || echo "请装 poppler"which dot || echo "请装 graphviz（仅 B 路 auto-layout 需要）" - Python detection script dependencies:
tikz-validator.pyandtikz-design-linter.pypure standard library, directlypython3run.pdf-overlap-checker.pyrequirespdfplumber+pymupdf，figure-diff.pyrequiresopencv-python-headless+scikit-image. When the system python has no pip, run with a uv temporary environment (cached after the first run):uv run --with pdfplumber --with pymupdf python references/pdf-overlap-checker.py file.pdf --jsonuv run --with opencv-python-headless --with scikit-image --with numpy python references/figure-diff.py ref.png out.png（pymupdfnot installed →line-through-node+node-overlaptwo types of geometry checks will ERROR out, not silently skip — do not ignore)
⓪.5 Entry mode routing (first question after ⓪, path fork point)
The skill now supports 4 generation paths— you must first determine which one to take before drawing.Default is path A; other paths are triggered by keywords。
| Path | Trigger keywords (user's original prompt) | Description | Status |
|---|---|---|---|
| A — Skeleton reuse | "Draw an X chart", "Help me draw a Y", no other mode explicitly indicated | Select one from the verified skeletons (B/C/D/E/F/G),copy everything + change content + don't touch layout. Fastest, most stable. Output visually similar to the skeleton | ✅ Default |
| B — Remix (assemble modules across skeletons) | "Something like combining D's radar with G's chart", "I want the left half of X + the right half of Y" | Select multiple skeleton parts, automatically assemble | 🚧 Not yet implemented,fall back to A |
| C — Original design | "unique layout", "replicate this ref.png", "design from scratch", "I don't have a suitable skeleton" | Design the layout from scratch (Module-First ③.A→③.D) → mandatory independent multi-camera review gate(④.5 end of document). ⚠️ mode C is most prone to collapsing on "the newest structure in the figure with no skeleton precedent", and generator self-review isstructurally blind | ✅ Existing path |
| D — Deposit into library | "Save this .tex into the library", "as a new skeleton", "add to examples", "deposit into the template library" | User already has .tex → automatically deposit into library as example-skeleton-{H..Z}-<topic>.tex |
✅ Go through Φ deposit channel |
| AUDIT — Finished-figure review | "Review this figure", "Can this figure be used?", "audit my figure", "figure looks unprofessional", "check the figure" — the useralready has a finished figure(do not draw a new one) | For the user-providedfinished figuredo a design review.With-image path: Read the image (vision) then run the rule-based review;No-image path: text-only, explicitly mark vision-only checks as "user must verify" | ✅ Go through Ψ review channel |
Go through A → continue ① ② ③ ④ ④.5 ⑤ ⑥ ⑦ (③ takes path A: select the best match from the 6 skeletons → copy everything → change content / don't touch layout / strictly follow the CONSTRAINTS section) Go through B → currently unavailable. Report to the user "Remix mode is not yet implemented; for now please use A skeleton reuse; if the part combination you want approximately exists in some skeleton, you can directly go through A and pick the closest one" Go through C → continue ① ② ③ ④ ④.5 ⑤ ⑥ ⑦ (③ takes the from-scratch path + Module-First ③.A→③.D sub-flow; ④.5 must run the "mode C independent multi-camera review gate"— see ④.5 end of document, cannot rely only on generator self-review) Go through D → skip ①-⑦, go directly to Φ deposit channel(see end of document) Go through AUDIT → skip ①-⑦ (do not draw a new figure), go directly to Ψ review channel(see end of document)
Decision rules(by priority):
- The user mentions "审查这张图 / 这张图能用吗 / audit my figure / 检查这张配图 / figure looks unprofessional", andthere is already a finished figure(the user gave an image path, or the image is already in
.writing/figures/）→ strong AUDIT(go through Ψ,do not draw a new figure） - The user mentions "存进库 / 入库 / 作为模板 / save to examples" → strong D(go directly through Φ)
- The user mentions "组合 X 的 Y + Z 的 W" → strong B(fall back to A + prompt)
- The user mentions "unique / original / recreation / from scratch / no reference image" → weak C(ask to confirm whether to go with A or C)
- otherwise → A(no need to ask, go directly along the skeleton path)
The difference between AUDIT and C reproduction(easily confused): AUDIT is "judging whether an already existing finished figure is good or not" (it does not produce a new figure, only an audit report); C reproduction is "redrawing a vector figure by following ref.png" (it produces a new figure.tex). If the user says "这张图能用吗 / 帮我看看这图" → AUDIT; if they say "照这张重画 / 复刻成 TikZ" → C.
The impact of mode selection on compile verification / vision-audit: because the skeleton in mode A has already passed layout verification, ④.5 focuses on "whether the content has completely departed from the skeleton theme (missed renaming, stale labels)";mode C goes through the full 18-item checklist + the mandatory "independent multi-shot review gate"(generator self-review in mode C was measured to miss core defects 3/3 times, so external adversarial review must be the fallback); mode D goes through the simplified audit of Φ.2.
① Drawing instructions (mandatory explicit output, cannot be skipped)
Load references/step1-instructions.md—it contains the complete 10-item element checklist, reference image measurement rules, the ASCII sketch method, the embedded visualization decision table,the density reference table (choose the tier according to paper complexity), the node shape/connection quick reference, and Pre-flight P1-P7.It is forbidden to "think it through in your head and write code directly"—skipping this step has a 100% rework rate.
At the same time load references/figure-rhetoric.md(design judgment, not syntax)—it decideswhether this figure should be drawn / which kind to draw, not how to write TikZ. It gives: the three narrative figures that a paper truly needs (motivated example / solution overview / results), the three paradigms of Figure-1 and the conditions under which each should be avoided (when gains are marginal, a performance teaser will inversely expose weaknesses), as well as four design rituals (the 30-second comprehension test / use only real entities and forbid Entity1/X placeholders / the same example running through the whole paper / draw a sketch on paper first—the comment block in step ① of this skill is the persisted form of the "paper sketch"). Figure-1 defaults to Paradigm A (running example + failure case), mechanism-level contributions use B, and only short papers with large gains and quantification use C.Also read _shared/core/house-style.md §9 (default layout of the paper's figure group): the introduction contains only one single-column small figure that "talks only about the problem" (motivating instance / gap map / why-X comparison,without any mechanism), place a full-width banner image at the top of the design section's first page; its name stage is the skeleton of each subsection and is referenced by the first sentence of that section; all subsequent method figures reuse the same running example;[t] The float lands "after the page currently being typeset when it is read", so the source of the design section's first figure often needs to be placed in the previous section's file with an explanatory comment. Project .claude/CLAUDE.md takes priority over house style.
Key insight: the output of step ① is not the "maximum-complexity version". First determine the paper's actual complexity (minimal / medium / complex / ultra-complex), then choose the figure tier.Starting from the complex version and then fixing flawsthanstarting from the appropriate tieraccumulates an order of magnitude more tokens — MMAlign's 11 rounds of iteration are the cautionary tale.
🔴 Mandatory materialization requirement(fig126 Tacotron2 lesson: the sub-agent loaded step1 but skipped the actual output, producing large blank areas):
Step ① mustactually output in text form(not "thought about it and moved on"), andthe first paragraph must be written into the comment block at the top of figure.texas evidence.Choose one of two forms, based on figure complexity:
🔵 Prerequisite before choosing form A/B(to eliminate the "node-count paradox" — tier judgment depends on the sketch, and the sketch depends on tier judgment, a circular dependency):
1. 先粗估档位（无需精确节点数，先看明显信号）：
① 含 hero 子结构 / 嵌入热力图 / 多 panel / ≥3 列 → 复杂档 → form B
② 含 fan-out / 时序生命线 / 12+ 模块 → 中等档 → form A 或 form B
③ 纯几何/单链/对比图（明显 < 15 节点）→ 极简档 → form A
2. 按粗判选 form 写注释块（form A 画 ASCII OR form B 写 narrative）
3. 注释块写完后**数节点 → ①.5 精确确认档位**
4. 若精确档位 ≠ 粗判档位 → 调整 form（极简误判为复杂 = 简化为 A；
复杂误判为极简 = ASCII 画不下 → 改写 B）
Iron rule: rough judgment first → write the comment block → ①.5 precise confirmation → adjust if necessary.Do not directly choose a form by intuition and then judge the tier by intuition。
Form A — ASCII sketch (minimal tier / medium tier without embedded viz)
% Step ① 设计文档
% 领域 / 格式 / 档位 / 整图 W×H cm / 信息流方向 / 行×列
% 模块列表 N 个，核心 = X / 连线逻辑 / 空间规划 rail x / 视觉强调
% ASCII 草图：
% +-----------+ +-----------+ +-----------+
% | Encoder |----->| Attention |----->| Decoder |
% +-----------+ +-----------+ +-----------+
% 预防 issues：[2-3 个坑]
Form B — Narrative design text (complex tier / hero substructure / embedded viz / multiple panels)
Complex figures cannot be fully expressed in ASCII; usenarrative spatial description— write a paragraph for each column/zone: (a) x/y range (b) internal substructure (c) relationship to adjacent columns (d) whitespace handling（In particular, anticipate where large blank areas might appear and write out how to handle them — fig126/137 lesson)
Write it at the top of figure.tex as a comment, and the sub-agent reads and verifies it at ④.5 Step 0. If the comment does not exist → blocker, go back to ① and redo.Note: form B does not require filling in a template; it uses "the designer's narrative thinking" to unfold the layout — the focus is the Philosophy section's UNFORGETTABLE Question: how do you lay it out so that a reviewer remembers one unique structure in 5 seconds?
①.5 Figure tier judgment (user-driven + automatic detection fallback)
🔴 Complexity is determined on demand, not complex by default(Batch 16 lesson: Philosophy First made the sub-agent default to examples 06's complex style, but when the user actually only wanted a medium-clear figure = overreach turning into a mess).
Step 1: Infer complexity from the user's original prompt keywords
| User prompt keywords | Inferred tier |
|---|---|
| "detailed / complete / includes benchmark / publication-level / overview / hyperparams / performance numbers" | Complex tier(follow the full Philosophy set: embedded viz + panel + formulas + multiple colors) |
| "Overview / Main architecture / Flowchart / Main flow / Schematic" | Medium tier(Clear mainstream + zones, 1-2 embedded elements) |
| "Geometric schematic / Formula comparison / Curve comparison" | Minimal tier(Single coordinate system or pure structure, no hero / no panel) |
Step 2: If the user's original prompt is unclear → default to the medium tier (this plugin's override rule)
This plugin targets systems papers, and the overall style leans plain. When the user does not explicitly state complexity,draw directly at the medium tier(clear mainstream + zones, restrained decoration), without asking. Deviate from the default in only two cases:
- The user mentions "hero figure / publication-grade overview / includes benchmark / detailed and complete" → upgrade to the complex tier
- The figure itself is pure geometry / a single chain / curve comparison (obviously < 15 nodes) → downgrade to the minimal tier
Forbiddenarbitrarily choosing the complex tier and drawing a "messy figure stuffed with panels"—on-demand is what counts as aesthetics. The embedded viz / multi-panel vocabulary in the Philosophy section is enabled in full only at the complex tier; the medium tier allows at most 1-2 embedded elements.
Step 3: After the user confirms, execute according to the table below
| Tier | Automatic judgment alternatives (when the user does not say) | Elements that this tiershould have(Philosophy moderately expanded) | ④.5 Self-evaluation strategy |
|---|---|---|---|
| Minimal tier | ≤15 nodes + no hero + no embedded viz | Single coordinate system / pure structure + necessary annotations;do not impose hero / panel | Among the 18 items, S8/S9/M8/E3/E12/V1 are marked N/A in one sentence |
| Medium tier | 15-30 nodes OR has hero | Mainstream + 2-3 zones + 1-2 embedded elements (optional) | Run all 18 items; E3/M8 with 0 candidates pass in one sentence |
| Complex tier | ≥30 nodes OR embedded viz OR multiple heroes | hero substructure expanded + ≥2 embedded viz + ≥1 panel + embedded formulas + ≥5 color zones | Run all 18 items, with emphasis on V1 |
Key principles：Minimal does not mean mediocre; complex does not mean it must be stuffed。Aesthetics lie in Philosophy (what is remembered in 5 seconds), density lies in the tier (according to user needs).
①.7 Dual-candidate layout preview (mandatory for this plugin; only after the user selects does deep iteration begin)
Rule: Each new figure must first produce 2 layout candidates, both compiled into PNGs for the user to choose from; only after the user selects does it enter the ④.5 deep iteration loop.
1. 在步骤 ① 产出 2 份设计文档（form A/B 注释块 ×2），两个候选必须有实质差异：
- 不同 skeleton（如 B-horizontal vs C-centralhero），或
- 不同主流向（横向 pipeline vs 纵向分层），或
- 不同信息组织（zone 划分方式 / hero 位置）
禁止"同布局换配色"凑数——配色差异在迭代阶段调，不算候选差异。
2. 每个候选走 ③ 生成 + ④ 编译（draft 质量：过 tikz-validator + 编译成功 +
无 Missing character 即可，跳过 ④.5 深度审查）。
3. 用 Read 展示两张 PNG，用 AskUserQuestion 让用户选（选项附一句布局差异说明）。
4. 用户选定 → 该候选进入 ④.5 完整视觉闭环；落选候选的 .tex 删除或留作素材。
Exemptions(go directly to a single candidate through the original process):
- Replication tasks (there is a reference figure, and the target form is already fixed)
- The user explicitly specifies the layout ("draw it as that kind with two columns left and right")
- Minimal-tier pure geometric figures (layout freedom is inherently low)
- Iteration rounds of ④.5/⑥ (candidates are selected only once, not reselected each round)
- D mode entry (does not draw a new figure)
② Load specialized rules
After determining the chart type,as neededLoad the corresponding files (see "On-demand loading index" below). Also load references/baselines.md(verified parameters) and references/lessons.md(common pitfalls); for pitfalls specific to this diagram type, see also references/lessons-by-type.md, and just read the corresponding entries as needed—no need to load the whole thing.
The baseline parameters are already the crystallization of 25 batches and 157 diagrams—use them directly, do not trial-and-error from scratch. Any deviation from the baseline must have a concrete reason.
③ Generate code (Module-First sub-process + two-layer decision gate）
🔴 Complex tier mandates the Module-First sub-process(Batch 16 lesson: a sub-agent wrote 800 lines of TikZ in one go → the whole diagram was a mess; draw part first, verify it, then stitch together = clean):
③.A — 先画 hero（最重要的中央子结构 + 嵌入 viz / 关键公式）
- 单独输出 figure.tex（只含 hero + 一个极简 frame）
- 编译 + 渲染 PNG → 单独审查 hero
- hero 内部 sub-layers / 嵌入 viz / 公式都干净后才继续
- 不要直接跳到完整图
③.B — 再加主流（管线 + zones 边界 + connecting arrows）
- 在 ③.A 的 hero 周围扩展：左右上下的 supporting modules + zone 边框
- 编译 + 渲染 → 审查框架是否清晰
- canonical fan-out / fan-in 在此阶段引入
③.C — 再加 information panels（hyperparams / benchmark / legend / 公式注释）
- 选**角落留白**放 panel（不是"塞满式填空白"）
- panel 之间间距 ≥ 1cm
- 编译 + 渲染 → 审查 panel 是否补充而不喧宾夺主
③.D — 整体审查（→ 进入 ④.5）
- 整图 Philosophy 检查（UNFORGETTABLE / 5 秒第一印象 / 主线眼睛轨迹）
- 18 项 last-mile bug 检查
Minimal / medium tiers may skip Module-First, and can write it all in one go.Module-First is mandatory only for the complex tier—its value is staged verification, avoiding an error in 800 lines of TikZ at once that wrecks the whole diagram.
Decision gates other than Module-First(Route B vs. from-scratch route):
Question 1: Is this diagram a pure structural diagram?(boxes + lines + grouping,noembedded heatmap/curve/bar/matrix,no multiple child nodes inside the hero) → Yes:Route B (auto-layout)
- Load
references/figure-spec.schema.mdto see the schema - Output
figure-spec.json(nodes, edges, zones, layout engine) - Run
python3 references/dot-to-tikz.py figure-spec.json→ producesfigure.tex - Proceed to ④ compilation + ④.5 visual feedback
- Applicable: architecture diagrams / pipelines / DAGs / protocol sequence diagrams / three-column mapping / technology roadmaps / multi-instance convergence
- Advantage: 0 coordinates chosen by Claude, 0 types of slightly slanted lines / frame-crossing / crowding bugs
Question 2: Rich visual diagram (embedded visualization / complex hero substructure / irregular layout) → From-scratch route + Module-First (③.A→③.D)
- Starting point:
references/tikz-template.tex(including preamble / fonts / color scheme / canonical arrow styles / defensive writing) - Load
references/visual-patterns.md(9 patterns: hero substructure, heatmap, line chart, bar chart, etc.) - Follow the ③.A→③.D sub-process: hero first → add main flow → add panels → overall review
- Complex connections (≥8 crossing risk): optional
python3 references/tikz-path-router.py spec.jsonA* obstacle avoidance
🎯 Arrows/connections must use the canonical pattern：tikz-template.tex 's 6 predefined styles (arrow / arrow short / residual / leader / fan_stub) each have mandatory conditions for use. The four most commonly violated: short arrows < 1.5cm must use arrow short(otherwise the tip consumes the whole stem, visually "only a head is left"); the stub segment of fan-out must use fan_stub(otherwise the spine breaks); straight lines must not add rounded corners(endpoints produce ghost arcs);|- / -| 's middle segment will cross frames, and PGF does not do obstacle-aware routing. Do not hand-write -{Stealth[scale=X]}, only adjust line width. For the complete ironclad rules, counterexamples, and fix patterns, see references/arrow-patterns.md——must-read before writing any connection, and the two checkers that must be run before compilation are also at the end of that file.
④ Compilation verification
# 字体探测：若 PingFang SC 不存在，自己改 .tex 里的 \setCJKmainfont 为本机可用字体
# （Linux 常见替代：Noto Serif CJK SC / Noto Sans CJK SC，用 fc-list :lang=zh family 查）
fc-list | grep -qi "PingFang SC" || echo "WARN: PingFang SC 缺失，请改 \setCJKmainfont"
xelatex -interaction=nonstopmode file.tex
grep "Missing character" file.log # 静默失败检查，关键
pdftoppm -png -r 300 file.pdf out # 产出 out-1.png
# overlap.json 落在 .tex 同目录（sub-agent ④.5 步用 Read 读这个绝对路径）
python3 references/pdf-overlap-checker.py file.pdf --json > "$(dirname file.pdf)/overlap.json"
# 跑完检查 overlap.json — 7 类检测：
# 基础 5 类（直接 fix）: text-overlap / text-overflow / off-center / text-line / line-crossing
# candidate 2 类（需 triage）: line-through-node / node-overlap
# ERROR 类大概率是真 bug 直接修；candidate 类是几何线索（heatmap 矩阵 / fan-in 收敛
# / panel 边界等常误报），sub-agent 在 ④.5 自评时按坐标对照 PNG 决定 fix 还是 ignore。
# 论文集成场景另跑排版尺寸闸门：references/preview-loop.py（详见 preview-loop.md）
④.5 Visual feedback mandatory closed loop (architectural core, cannot be skipped)
Your code generation is "blind writing"—when you get to line 800 of TikZ you don't know what it will render as. All label collisions, axis titles pressing on text, lifelines out of bounds, submodules squeezed, math symbols rendering oddly—problems like these cannot be detected by gates 1+2; only by seeing the PNG can you find them.
Goal restatement: what the user wants is not "one-shot generation", but "the diagram delivered to them must be perfect".It doesn't matter how many intermediate iterations there are, as long as the diagram is perfect in the end。
Mandatory process：
0. Read 渲染出的 out-1.png + 视觉直觉先行（应用 3 大法则，见下）
1. Read overlap.json（路径 = .tex 同目录的 overlap.json，步骤 ④ 跑出来的结构化几何检测）
2. 加载 references/visual-review-checklist.md（强制审查清单）
3. 逐项回答该文件列出的每一项 Y/N
每项必须有一句证据（"我在 PNG 中看到…" 或 "overlap.json 中 N 处 line-through-node 我标为 …"），不允许凭印象
4. 任一项 N → 列入 blocker → 输出 patch → Edit → 回 ④ 重编译 → 回 0
5. Step 0 + 全部 18 项 Y → **把图给用户看**（用户终审，AI 视觉有盲区）
6. 用户也通过 → 交付
Step 0: visual intuition first (must be done before the 18 Y/N items)
Put yourself in the shoes of a reader seeing this diagram for the first time,scan the entire diagram using the 3 major laws, and output 5 paragraphs of evidence:
| Step 0 check | Output requirements | Law |
|---|---|---|
| A. 3-second first impression | Write down "the 3 things seen within 3 seconds" (e.g. "blue main flow left→right / hero in the middle / 3 heads on the right") | Law 1 |
| B. Main-line eye trajectory | Find themost important data flowin the diagram, and follow it with your eyes from start to end. Any "stuck" position = blocker (e.g. fig97 an arrow escaping the Pedersen box / fig118 tip hitting the axis / fig120 isolated colored dot) | Law 2 |
| C. Deletion test | Listelements suspected to be deletable(isolated decoration / redundant leader / duplicate label). If empty, one sentence "no deletable elements" | Law 3 |
| D. Aesthetic regression test(when round ≥ 2) | Compare with the previous round's PNG: this round fixed X bugs but did it introduce new aesthetic problems (lost symmetry / broken parallelism / uneven spacing)? | Law 3 |
| E. Large blank areas + ① annotation verification | Scan the entire diagram for no blank area larger than > 3cm × 2cm (thin lines don't count as filling; there must be box/text/viz); the figure.tex header has the form A/B annotation block.fig137 lesson: writing "rail filled" = self-deception. If there is a large blank area → go back to ① and re-plan the layout, not modify the .tex | Law 3 |
Any Step 0 item failing = blocker, add it to the patch list.Only after Step 0 passes do you start the 18 items of Step 3。
Why Step 0 comes before the 18 items: the 18 items are mechanical verification (detailed physical examination), and it's easy to fall into "item-by-item Y / overall bad". Step 0 is visual intuition (overall ECG), forcing the sub-agent to look at the diagram from the reader's perspectiverather than the generator's perspective. Both are indispensable.
overlap.json handling(S8 + E12 companion):
errors[]text-overlap / text-overflow / off-center / text-line in are most likely real bugs—locate the PNG by coordinates and fixerrors[]line-through-node in are candidates(E12)—triage them one by one:- hits on matrix cells / heatmaps / neural network convergence nodes → ignore (intentionally semantic, known false positives)
- Path detours through unrelated elements (e.g. a dashed leader passing through a box / a long curve pressing on a node) → fix, re-route or change z-order
errors[]node-overlap in is a candidate(S8) — triage one by one:- drop-shadow / parent-child have already been filtered, nearly everything hit is a real problem
- panel-overflow boundary nodes (e.g. a PGM node's bottom exceeds the panel by 1-3pt) → adjust coordinates
- two sibling nodes genuinely overlap → separate them
- Write the triage decisions into the S8 / E12 evidence of the ④.5 self-review ("node-overlap N places: X fixed (panel boundary), Y ignored"; "line-through-node N places: M fixed (path detour), K ignored (matrix cell)")
Optimization rules(Batch 9 measured: fig89 took 32min / fig86 took 55min, most of the time spent on repeated Read and triage):
- Load Reference documents only in the first round —
SKILL.md/baselines.md/lessons.md/visual-patterns.md/step1-instructions.md/visual-review-checklist.mdafter reading once in round 1,do not repeatedly Read in subsequent rounds(already in context). Only Read what changed: PNG + overlap.json + the figure.tex fragment you just edited - Empty detection skips triage —
overlap.jsoninline-through-nodearray is empty → E12 answers Y directly: "0 candidates in overlap.json".node-overlapSame reasoning → S8 answers Y directly.Do not write reasoning for an empty array - Incremental triage — at round N only write reasoning for candidates thatnewly appearedafter round N-1; reuse conclusions from earlier triage ("same as round 1 place 3, still ignore")
- ERROR takes priority over candidate — first fix
text-overlap/text-overflow/text-line/off-centerthese 4 categories of ERROR (these are very likely real bugs), then go back to triage candidates. Avoid fixing ERROR and re-triaging the same batch of candidates at the same time
These 4 items combined are estimated to save 30-50% of the time, with no loss of quality.
High-miss blind spots: the items marked with ⭐ in the checklist (S8/S9/M8/E3/E9/E12) are the high-miss ones measured in R3-100 — watch them with priority during review.
No round limit. This is the biggest difference from before — previously max 2 rounds meant "make do and deliver", now it isas long as there is still 1 blocker, you cannot deliver. 3 rounds, 5 rounds, 8 rounds are all fine, as long as the final figure is perfect.
Psychological resistance: after 2-3 rounds you will have a strong urge of "it's about good enough" — this is cognitive fatigue, not the figure becoming perfect.The urge appearing = the blocker is still there. Force yourself to answer every item and write out the evidence.A user can spot in 1 glance the problems you missed after 2 rounds — this shows single-perspective self-review is unreliable, you must rely on exhaustive checklist enumeration。
Escalation mechanism：
- If there are still ≥5 blockers at round 3 → local patching is hopeless, go back to step ① and redesign the drawing instructions
- The same blocker not fixed for 2 consecutive rounds → your fix direction is wrong, change your approach
- Complex figures (≥40 elements) / mode C always: spawn multiple-lens review agents in parallel (see "mode C independent multi-lens review gate" below), collect blockers uniformly
- After the self-review + adversarial agents all say 0 blockers, still show the figure to the user first——Issues that the human eye can spot but that sub-agents + self-evaluation all miss (real case: in Round 10 the user instantly pointed out that the CMAM title cuts off the border, the arrow pierces into the box, and the junction dot is stabbed by the tip — not one of these 3 was found by me or the 2 adversarial agents).The user's vision is the final gate, not a point to be bypassed。
Mandatory constraint: Before delivery you must be able to state, in the PNG,specific visual details(which colors are where, which side a zone is on, the diagonal features of the heatmap, etc.), proving that you actually took in the visual input.
Single-point minimal-change principle: Each round's patch changes only one class of issue (e.g., "all labels overlap" or "all axis titles were not moved down"); do not make large changes in one round — large changes introduce new bugs. One class of blocker per round. Prefer using yshift/xshift for fine-tuning positions, avoiding changes to the main coordinate framework.
mode C mandatory independent multi-lens review gate (cannot be skipped)
mode C (drawing from scratch, with no skeleton precedent) in practice crashed 3/3 times on "the newest, most unprecedented structural element in the figure," while generator self-review was systematically blind to it — three figures went through 4/3/1 rounds of self-review, all passed self-evaluation, and all missed the core defects. Therefore, after mode C's ④.5 completes Step 0 + the 18 items,the top-level orchestrator must separately start 4 independent agents with blank contexts to conduct adversarial review(the four lenses: geometry / semantic / text / aesthetic). Multiple self-reviews in the same context do not count. For the full workflow, the four-lens division of labor, and the delivery conditions after the gate, see references/mode-c-review-gate.md。
⑤ User final review + delivery
- Show the PNG to the user(not asking "Am I done?", but directly displaying the result)
- When there is a reference image, also run
python3 references/figure-diff.py <ref.png> <out.png>to get SSIM; for 3×3 regions with < 0.85, examine them together with the user - User points out an issue → return to ④.5, make the issue a blocker for the new round; user has no issue → deliver
Step ⑤ no longer independently performs the "three-pass self-review method"— all self-review has already been done in ④.5's exhaustive checklist. Doing the same set of reviews twice is only a source of cognitive fatigue, not a quality improvement.
⑥ Iterate to perfection (no upper limit)
For round rules and the escalation mechanism, see the two sections "no upper limit on rounds" and "escalation mechanism" in ④.5.
⑦ Experience accumulation
- Issues that took more than 2 times to resolve → append to
references/lessons.md(general) orreferences/lessons-by-type.md(figure-type-specific); batch-by-batch re-review goes toreferences/lessons-archive.md, not loaded by default - Discover better parameters → update
references/baselines.md（only upgrade, never downgrade） - Content already covered by global rules / Python checkerdo not write repeatedly
Φ accumulation channel (D mode — the user already has a .tex to be added to the library as a new skeleton)
When the user already has a successfully compiled .texand wants to solidify its layout into a reusable skeleton, use this channel (⓪.5 choose path D): do not draw a new figure; output the added-to-library skeleton file + updated gallery. For the full workflow see references/skeleton-intake.md, key points: compilation verification → simplified vision-audit → three-tier library-admission decision by comparing similarity with the existing 6 skeletons → naming and letter assignment → automatically generate the USAGE header → write to the library and update the README gallery → remind to add CONSTRAINTS.
Difference from ⑦: ⑦ Accumulate abstract lessons and baseline parameters; Φ accumulates complete, reusable figure templates. The library is self-growing; this is the core mechanism for the long-term compounding of this skill.
Ψ Review channel (AUDIT mode: review a user's existing finished figure)
When the user already has a finished figure and wants to "review whether this figure is usable," use this channel: do not draw a new figure, produce an advisory review report. See the complete workflow in references/figure-audit.md, key points: a vision-preferred path with images, an explicitly degraded path without images (vision-only items marked "user must verify"), reuse of the 18-item visual review checklist, a defect-hunting report with high/medium/low severity, all submitted to the user for judgment.
Design principles (countering model inertia)
Stereotypes that are easy to fall into (must be on guard against):
- "I have it clear in my head, just write the code" → It is forbidden to skip step ①, "thought about it" ≠ "thought it through"
- "I can estimate proportions" → No. Replication requires pixel-level measurement; relying on feel deviates by 15-20%
- "The box size is about right" → No. Reference figures are usually flat and wide, 2:1~3:1,do not default to a square
- "I've revised it 3 rounds, that's about enough" → The standard does not lower because of effort. If blockers remain, keep fixing
- "The user won't notice this small overlap" → They will notice. At 300dpi it is perfectly clear
- "A coordinate difference of 0.2cm doesn't matter" → 0.2cm is 24 pixels on the rendered figure
- "If the information density is insufficient, cram things in" → Counterexample. A simple paper figure should be simple—Bayesian networks/geometry/comparison figures naturally have few elements; forcing in a hero and embedded visualizations is contamination.
tikz-design-linterIt is now advisory; determine density according to the paper's actual complexity
Information density matches paper complexity: complex model architecture figures allow 30+ elements + hero substructures + embedded visualizations; a simple flowchart with 5-10 elements + a clear layout is enough.Do not draw every figure at maximum complexity. See details in step1-instructions.md 's "information density judgment".
Common chart types
| Type | Layout | Scenario |
|---|---|---|
| System architecture diagram | Bottom-up layering | Device→cloud→chain, hardware→middleware→application |
| Protocol/flowchart | Left→right or top→bottom | Timed steps, signal processing |
| Data pipeline | Left→right horizontal series | Input→processing→output, each step with a different shape |
| Circuit/constraint principles | Left→right | ZK circuits, signal pipelines, compilers |
| Data mapping/transformation | Left-middle-right three columns | Format conversion, API adaptation |
| Timing interaction | Multiple lifelines + horizontal messages | Multi-party protocols |
| Compare solutions | Left-right side by side | Solution A vs B, ≥3cm in between |
| Geometry/mathematics | Coordinate system + geometric elements | Algorithm principles, vector relationships |
| Aggregation of multiple instances | Three-column horizontal layout → convergence | Federated learning, distributed |
| Data visualization hybrid | Waveform/bar/heatmap embedded in the diagram frame | Signal processing, deep learning attention |
On-demand index loading
After determining the chart type/workflow stageonly thenload the corresponding file:
| Trigger condition | File |
|---|---|
| Enter step ① (design judgment: whether to draw / which type to draw / Figure-1 paradigm / default layout for paper figure sets) | references/figure-rhetoric.md + _shared/core/house-style.md §9 |
| Once the figure set for the entire paper is ready, run a full-set figure narrative review (editor pass) before submission | references/figure-rhetoric.md §5 |
| A single figure contains multiple subfigures; panels need to be planned and the stitched overall figure reviewed as a whole (compose multi-panel figure) | references/figure-rhetoric.md §6 |
| Enter step ① | references/step1-instructions.md |
| AUDIT mode (Ψ review channel) | references/figure-audit.md + references/visual-review-checklist.md(18 items) |
| D mode (Φ sedimentation channel: existing .tex ingested as skeleton) | references/skeleton-intake.md |
| Step ② (any TikZ figure,must load） | references/baselines.md + references/lessons.md + references/visual-patterns.md |
| Step ③ decision gate | references/figure-spec.schema.md(B-path spec) |
Step ③ take B path → run dot-to-tikz.py |
(script, no Read needed) |
| Step ③ use template/from scratch → use TikZ | references/tikz-global-rules.md + references/tikz-template.tex |
| Step ③ before drawing any connection (required reading) | references/arrow-patterns.md(6 canonical styles + short arrow/fan_stub/rounded corners/L-bend iron rules + pre-compile checker) |
| Step ③ complex tier needs to embed viz / panel / formula | references/tikz-snippets/ ⭐ Prefer assembling from snippets rather than writing from scratch(includes 6 hand-crafted templates: attention-heatmap / bar-chart / hyperparams-table / multi-zone-palette / pipeline-stages / formula-box) |
| Step ④.5 visual feedback each round | references/visual-review-checklist.md(18-item mandatory checklist) |
| Step ④.5 and mode C (drawn from scratch, no skeleton precedent) | references/mode-c-review-gate.md(orchestrator independently spawns four-lens adversarial review) |
| Color scheme requirements | references/tikz-colors.md |
| Layered architecture diagram | references/layered-architecture.md |
| Sequence interaction diagram | references/sequence-diagram.md |
| Data pipeline diagram | references/data-pipeline.md |
| Three-column mapping diagram | references/three-column-mapping.md |
| Geometric/mathematical schematic | references/geometry-math.md |
| Figures containing data visualization | references/data-visualization.md |
| Step ⑤ has reference image | references/figure-diff.py(script) |
Do not load files not listed——saves tokens.
Python helper scripts (just execute, do not Read)
| Script | Purpose | When to run |
|---|---|---|
dot-to-tikz.py <spec.json> |
B path: spec → graphviz auto-layout → TikZ | Structured diagram step ③ |
tikz-validator.py <file.tex> |
Slight skew/overflow/collision/direction reversal (geometry/syntax gate) | Must run before compiling |
tikz-design-linter.py <file.tex> [--type ...] |
Element count/size ratio/line type/hero/embedded viz (design ambition gate) | Must run before compiling |
pdf-overlap-checker.py <file.pdf> [--json] |
PDF coordinate-level overlap + line-through-node + node-overlap geometric detection (7 categories：text-overlap / text-overflow / off-center / text-line / line-crossing / line-through-node / node-overlap） | Must run after compiling |
figure-diff.py <ref.png> <out.png> |
SSIM + 3×3 regional difference | Must run for reproduction tasks |
tikz-path-router.py <spec.json> |
A* automatic obstacle avoidance path | ≥8 connections optional |
These scriptsas a black box—do not read the source code into context, just run --help to see the parameters.
Domain adaptation
After receiving the inputfirst identify the paper's field(computer science/cryptography/biology/physics/chemistry/AI/networking/systems/blockchain, etc.), and choose terminology and layout style as an expert in that field.