Distill figure revision heuristics

README.md

@@ -31,12 +31,15 @@
 ## 特点
 
 - **论点优先**：每张图只承担一个不可重复的论证任务，每个对象和边都必须能回到论文证据。
+- **语义源与风格源分权**：正文、caption 与用户确认的目标版本先共同解决冲突；核对后的原图固定拓扑与变量，风格参考只提供兼容的字体、描边、配色和密度。
 - **整篇图形系统**：统一字体、大小写、描边、箭头含义、颜色、形状、panel label、legend 和信息密度。
 - **Anchor-first**：先把架构图或复用度最高的图稳定下来，再让后续图沿用同一视觉语言。
 - **反 PPT 构图**：拒绝等宽圆角卡片、重复 caption 的大标题、通用左到右产品流水线、装饰外框、阴影和渐变。
 - **技术几何承载语义**：优先使用开放拓扑、持久状态条、队列、资源单元、内存格、lifeline、timeline、fan-out / fan-in。
 - **编码维度不混用**：设备身份与验证/拒绝状态独立编码；关键差异同时使用颜色与非颜色通道，保证灰度可读。
+- **语义层级决定几何**：所有权、因果独立性和更新主体决定是否独立成模块，论点重要性只决定视觉强调；peer、nested、metadata、field 与 status 只是常见模式，不是硬分类。
 - **母版布局 + 外科式修订**：先搜索整张图的 argument grammar，稳定后一次只改一个问题，并记录必须保持的全部不变量。
+- **把反馈翻译成结构修复**：区分“太像流程图、过度抽象、不像系统图、太死板、太松散/箭头太多”，选择不同的 grammar、层级和连接修复，而不是反复换颜色。
 - **四阶段验收**：分别检查语义、视觉、跨图一致性和编译页面；生成成功不等于任务完成。
 - **紧凑会议版面**：优先尝试单栏，在扩大到双栏之前先缩短标签、拆分论点、修复内部留白。
 - **隐私友好的公开版本**：仓库中的迭代案例已抽象化，不包含具体未发表论文名称或私有图片。
@@ -50,6 +53,8 @@
 | 对象如何移动、转换或依赖 | directed open topology |
 | 谁在什么时候发什么消息 | distributed protocol timeline |
 | 状态如何变化、何时可回收 | state machine / lifetime bands |
+| 哪些输入决定哪些估计或字段 | field-provenance map |
+| 多个论文定义的输入如何实例化结构化记录 | parameterized contract / ledger |
 | 为什么某个调度或分配更好 | concrete schedule + occupancy |
 | 容量、重叠或关键路径在哪里 | resource / memory / critical-path schematic |
 | 候选如何剪枝、排序和提交 | tree / lattice / candidate matrix |
@@ -125,7 +130,7 @@ skill 会根据请求进入四种模式之一：
 
 1. **Plan**：提取整篇论证结构，给每张图分配唯一 claim、grammar 和目标栏宽。
 2. **Create**：建立 figure brief 与 encoding ledger，冻结视觉系统，生成母版布局并迭代。
-3. **Revise**：对照论文诊断现有图，一次只做一个语义修订，并复查全图不变量。
+3. **Revise**：对照论文诊断现有图；只要求审阅时返回修订合同，要求改图时一次只做一个语义修订并复查全图不变量。
 4. **Audit / Integrate**：不强制重画，只完成语义、视觉、一致性、LaTeX 和编译页检查。
 
 完整创建流程为：
@@ -145,7 +150,7 @@ paper claim
 完成证据随模式变化：
 
 - **Plan**：返回 figure program、视觉契约与未解决的语义门槛；图片和 PDF 验证标记为 `N/A — planning only`。
-- **Create / Revise**：说明 claim、figure role、目标栏宽、最终图片路径、semantic / visual 结果，以及适用的 consistency / paper 结果。
+- **Create / Revise**：实际生成或改图时说明 claim、figure role、目标栏宽、最终图片路径、semantic / visual 结果，以及适用的 consistency / paper 结果；只读修订方案返回诊断与修订合同，并将图片结果标为 `N/A — planning only`。
 - **Audit / Integrate**：列出实际执行的检查；没有 anchor、相邻图、LaTeX 工程或最终图片时，明确标记 `N/A — 原因`，不能假称通过。
 
 若执行了统一外边距裁剪，还应记录参数；任何模式都应说明仍未解决的歧义或论文证据缺口。
@@ -157,6 +162,10 @@ paper claim
 - 架构图优先画清 `input -> state -> decision -> execution -> feedback` 的闭环，不要优先塞全组件。
 - 一张图同时解释 overview 与 mechanism 且文字开始缩小时，先拆图，不要直接扩大到双栏。
 - 参考图先拆成 argument grammar、composition grammar 与 style grammar，只复用其中与新论文逻辑兼容的部分。
+- “太像流程图”通常要换 grammar 或拆图；只换配色无法修复顺序骨架。
+- “更抽象”不等于使用云、波浪或有机曲面；系统论文通常需要 records、ports、buses、matrices、fields 和 resources 这一层结构化抽象。
+- 每条语义连接和承载论点的小图形都应有论文中的确切含义；若 checkmark、重复 tile 或线性序列会暗示未被正文支持的独立性、固定数量或顺序，就改为 aggregate field、区间、尺度或真实 trace。纯布局 guide 必须明确不编码机制。
+- 局部修线反复漂移、牵连其他连接或因密度持续误接时，应重构端口、字段对齐或关系层级，不要继续修线。
 - 局部修订后要检查所有标签、箭头、数量和边框；图像模型的局部编辑可能造成全局漂移。
 - 裁边只能移除统一的外部空白，不能修复半空 panel、错误比例或缺失关系。
 - 图在大尺寸预览里好看并不重要；缩放到最终栏宽后，读者仍能迅速找到 novelty 才重要。

README_en.md

@@ -29,11 +29,21 @@
 ## Highlights
 
 - One non-overlapping job and earned claim per figure.
+- Separate semantic and style authority: paper text, captions, and the user's
+  confirmed target version resolve conflicts first; the reconciled source
+  figure fixes logic while a style reference contributes only compatible
+  visual tokens.
 - Paper-wide typography, color, shape, arrow, legend, and density tokens.
 - Anchor-first generation for cross-figure consistency.
 - Anti-slide composition: no equal cards, title banners, generic pipelines, decorative outer frames, shadows, or gradients.
 - Independent visual channels for identity, state, outcome, and relationship type.
+- Semantic-rank geometry separates structure from emphasis: ownership, causal
+  independence, and update authority determine module boundaries, while claim
+  salience controls visual prominence. Peer, nested, metadata, field, and
+  status treatments are common patterns rather than an exhaustive taxonomy.
 - Mother-layout search followed by one-purpose semantic edits with invariant ledgers.
+- Critique-driven structural repair for figures that feel flowchart-like,
+  over-abstract, non-system-like, rigid, loose, or connector-heavy.
 - Four acceptance passes: semantic, visual, consistency, and compiled paper.
 - Single-column-first composition and explicit whitespace diagnostics.
 - Public examples contain no unpublished project names or private figures.
@@ -45,6 +55,8 @@
 - Control-plane/data-plane views
 - Directed request, data, and dependency topologies
 - Protocol timelines and lifecycle/state figures
+- Field-provenance maps and structured estimate/state records
+- Parameterized contracts and structured-record ledgers
 - Scheduling, allocation, resource, memory, and critical-path schematics
 - Search-space and candidate-selection illustrations
 - Matched baseline/proposed comparisons
@@ -93,7 +105,9 @@ The skill routes work into four modes:
 
 1. **Plan:** assign each figure a claim, grammar, and target width.
 2. **Create:** build the figure brief and encoding ledger, freeze the visual system, generate a mother layout, and iterate.
-3. **Revise:** diagnose against paper evidence, make one bounded semantic edit, and recheck all invariants.
+3. **Revise:** diagnose against paper evidence; return a revision contract for
+   review-only requests, or make one bounded semantic edit and recheck all
+   invariants when an image change is requested.
 4. **Audit / Integrate:** validate semantics, visual consistency, LaTeX placement, and the compiled page without forcing regeneration.
 
 Core flow:
@@ -108,9 +122,25 @@ paper claim
   -> compiled-PDF validation
 ```
 
+## Iteration rules
+
+- “Too much like a flowchart” requires a grammar change or split, not a palette
+  swap.
+- “More abstract” usually means records, ports, buses, matrices, fields, and
+  resources—not clouds, waves, or decorative surfaces.
+- Keep macro modules aligned while varying internal technical primitives by
+  semantic role; alignment need not produce rigid identical grids.
+- Give every semantic connector and claim-bearing micro-glyph a paper-grounded
+  meaning. Replace examples that imply unsupported independence, fixed counts,
+  or order with an aggregate field, interval, scale, or faithful trace; mark
+  neutral guides as non-semantic.
+- If connector edits repeatedly drift, disturb other attachments, or remain
+  unstable under high density, redesign ports, row alignment, grouping, or
+  semantic level instead of continuing line surgery.
+
 ## Definition of done
 
-Completion evidence is mode-aware. **Plan** returns the figure program, proposed contracts, and unresolved gates, with asset and PDF checks marked `N/A — planning only`. **Create / Revise** reports the claim, role, target width, final asset, semantic and visual results, plus consistency and paper results when those comparisons exist. **Audit / Integrate** reports the checks actually performed and marks missing artifacts or evidence `N/A — reason`. A paper-integration request is incomplete until the containing compiled page has been rendered and inspected.
+Completion evidence is mode-aware. **Plan** returns the figure program, proposed contracts, and unresolved gates, with asset and PDF checks marked `N/A — planning only`. **Create / Revise** reports the claim, role, target width, final asset, semantic and visual results, plus consistency and paper results when those comparisons exist. A planning-only revision instead returns the diagnosis and revision contract with asset results marked `N/A — planning only`. **Audit / Integrate** reports the checks actually performed and marks missing artifacts or evidence `N/A — reason`. A paper-integration request is incomplete until the containing compiled page has been rendered and inspected.
 
 ## Optional crop helper
 

skills/systems-paper-figurecraft/SKILL.md

@@ -18,8 +18,9 @@ Choose one mode before doing work:
   generate images unless the user also asks for generation.
 - **Create:** Recover the claim, generate a new semantic schematic, validate
   it, and integrate it when paper sources are available.
-- **Revise:** Diagnose the current figure against the paper, preserve accepted
-  semantics and style, and make bounded semantic edits.
+- **Revise:** Diagnose the current figure against the paper and preserve
+  accepted semantics and style. Return a read-only revision contract when the
+  user asks for a plan or critique; otherwise make bounded semantic edits.
 - **Audit or integrate:** Inspect semantics, consistency, final-size
   readability, LaTeX placement, and the compiled page. Do not force a new
   generation when review or integration alone satisfies the request.
@@ -42,11 +43,12 @@ For creation or semantic revision of systems schematics:
 - If image generation fails, wait once and retry the accepted prompt. If the
   retry fails, stop and report the blocker.
 
-Apply completion gates by mode. A created or revised figure must pass semantic
-and visual checks; run consistency checks when an anchor or neighboring figure
-exists, and run the compiled-paper check when the task includes paper
-integration. Mark an unavailable gate `N/A` with a reason instead of claiming
-it passed. Plan mode produces contracts, not a completed figure.
+Apply completion gates by mode. A created or materially revised figure must
+pass semantic and visual checks; run consistency checks when an anchor or
+neighboring figure exists, and run the compiled-paper check when the task
+includes paper integration. A planning-only revision returns diagnosis,
+proposed contracts, and invariants, with asset checks marked `N/A`. Mark an
+unavailable gate `N/A` with a reason instead of claiming it passed.
 
 ## 1. Recover the paper argument
 
@@ -60,6 +62,10 @@ Create a figure brief using [contracts.md](references/contracts.md). Define:
 - the exact paper evidence supporting every object and edge;
 - the system boundary, existing substrate, and novel mechanism or state;
 - inputs, outputs, ownership, control, multiplicity, and feedback;
+- semantic versus style authority when references serve different roles;
+- peer, nested, conditioning-metadata, field, and status relationships;
+- the meaning and forbidden implications of every claim-bearing glyph and
+  semantic connector, with neutral guides marked non-semantic;
 - exact labels, topology, arrow directions, and final placement width.
 
 Flag contradictions instead of drawing through them. For an architecture,
@@ -79,8 +85,12 @@ the original page and figure rather than relying on a textual mention. Separate:
 - **style grammar:** typography, stroke, palette, density, whitespace, and
   glyphs.
 
-Reuse compatible grammar only. Never copy paper-specific labels, mechanisms,
-brand marks, or exact geometry.
+When logic must stay unchanged while style changes, first reconcile paper text
+and captions with the user's confirmed target version. Stop if their conflict
+remains unresolved. Then treat the reconciled source figure as semantic
+authority for topology and the style reference only as a token library. Never
+copy labels, mechanisms, people, icons, brand marks, layout grammar, or exact
+geometry from a style-only reference.
 
 ## 2. Plan the paper-wide figure program
 
@@ -109,6 +119,12 @@ Read [figure-grammars.md](references/figure-grammars.md) and choose by the
 question the figure answers, not by component names. Split overview and
 mechanism views when one canvas cannot keep both legible.
 
+Also split panels when a shared canvas falsely implies sequence or forces
+incompatible grammars, even if the labels remain legible. Calibrate abstraction
+between generic card pipelines and organic concept art. Prefer structured
+systems primitives—records, ports, buses, matrices, fields, resources, and
+state—whose internal geometry varies by role.
+
 Reject any composition that behaves like a slide:
 
 - equal-width rounded cards or numbered stages;
@@ -138,13 +154,31 @@ Represent computation graphs as faithful open DAGs with visible input, output,
 branching, fan-in, skip edges, and optional ellipses. Never replace them with
 a tidy but false ring or square.
 
+Use paper-defined ownership, causal independence, and update authority to
+decide whether an element needs an independent boundary. Use claim salience to
+set prominence, not independence. Treat peer, nested, conditioning-metadata,
+field, and status treatments as common patterns, not an exhaustive taxonomy.
+Define complete claim-critical macro- and micro-edge inventories and priorities;
+never use an arbitrary count to hide a true dependency.
+
+Give every claim-bearing chip, semantic line, mini-graph, tile, checkmark, or
+repeated item one exact paper meaning. Mark neutral guides and dividers as
+non-semantic. Reject an illustration that implies unsupported independence,
+fixed counts, ordering, or item-level outcomes; show an aggregate field or
+faithful trace instead.
+
 ## 6. Generate the mother layout
 
 Read [generation-prompts.md](references/generation-prompts.md). Build a
 constrained prompt from the figure brief, visual-system contract, encoding
 ledger, exact text whitelist, semantic invariants, target width, composition
 proportions, and forbidden styles.
 
+When semantic and style references differ, state their authority separately in
+the prompt. List claim-critical macro edges, required micro edges, relationships
+encoded by attachment/containment/alignment, and the meaning of every internal
+glyph.
+
 Use early generations to search whole compositions. Reject a polished layout
 when its visual center, causal order, panel proportions, or grammar is wrong.
 Accept the mother layout only after the claim, topology, arrow directions,
@@ -166,6 +200,11 @@ Recheck the whole image after every edit. Reject an edit that fixes one issue
 but changes unrelated semantics; return to the last accepted image. Regenerate
 with a stricter whitelist when repeated text correction drifts.
 
+If bounded connector edits repeatedly reroute other edges, or attachment
+density makes correctness unstable, stop line surgery. Redesign ports, row
+alignment, grouping, or the relation's visual level so the correct topology
+becomes geometrically easier to generate.
+
 ## 8. Validate at paper scale
 
 Read [validation.md](references/validation.md) and run the applicable passes:
@@ -207,7 +246,8 @@ balanced and only for uniform near-white raster margins.
   generating or semantically editing an image.
 - Read [validation.md](references/validation.md) before accepting a figure.
 - Read [iteration-playbook.md](references/iteration-playbook.md) when a
-  generation remains slide-like, drifts semantically, or wastes paper area.
+  generation remains flowchart-like, over-abstract, rigid, loose,
+  connector-heavy, semantically ambiguous, or wasteful of paper area.
 
 ## Return mode-aware completion evidence
 
@@ -216,7 +256,9 @@ balanced and only for uniform near-white raster margins.
   only`.
 - For **Create or Revise**, report the accepted claim, figure role, target
   width, final asset, semantic and visual results, applicable consistency and
-  paper results, and remaining uncertainty.
+  paper results, and remaining uncertainty. For a planning-only revision,
+  return the diagnosis and revision contract and mark asset results `N/A —
+  planning only`.
 - For **Audit or Integrate**, report every check actually performed and mark
   unavailable evidence `N/A` with its reason.