workflow_change_visualization

Z3 全文↑ Z2 条目

道-方法 · 道层 skill 全文

本页是 <code>rules/skills/drafts/workflow_change_visualization.md</code> 的逐字投影（仅隐私清洗，零改写）。

时点提示：本页是仓内文件 rules/skills/drafts/workflow_change_visualization.md 的逐字投影（仅做隐私清洗：仓库根绝对路径→相对路径、家目录→~/；除此零改写）。若源文件后续有修订，以仓内真源为准。

报告元数据（frontmatter）

name: workflow_change_visualization
status: draft (Beta) — 2026-06-15 起草（RV-VIS，session b74c2ff8）；晋级前需在 ≥1 份真实变更报告上按本 skill 产 before/after 图、过 check_report_completeness 的 RC5、且无背景读者只看图能复述变更
version: 0.1.0 (draft)
tier: 道（方法引导 / 报告可视化判断）
description: 记录变更的报告（实现 / 走查 / 迭代 / 设计）里，怎么判断这次变更值不值得画图、该画哪种图（结构对比还是流程对比）、画前怎么 look-back 真实记录取证、怎么把报告组织成「主要看 before/after 图就能把握大方向」。触发场景：写涉及架构 / 结构 / 流向变更的报告、判一份变更报告的可视化够不够好、给报告设计 before/after 架构图。格式骨架（mermaid 模板 / 三色 / 节点边语义）归术 skill bestpractice_markdown_report；本 skill 管选图与组织的判断。

变更可视化：画什么、何时画、怎么组织（道）

道 skill。结果确定性优先。目标是替认知带宽有限的人省阅读：AI 多花力气把变更画成 before/after 图 + 标注关键变化，让人主要看图就能把握大方向，要深究再读正文。格式骨架（模板 / 三色 classDef / 节点边语义 / 降级兜底）在术 skill bestpractice_markdown_report，本 skill 不重述。

一句话

写记录变更的报告时，先判这次变更值不值得画图（非平凡的结构 / 流向变化才画），再判该画哪种图（Simon 状态描述 vs 过程描述），画前先 look-back 真实记录取证（不凭空画），最后把报告组织成首屏一张 before/after 图加一句判决。

何时用 / 不用

用：写实现 / 走查 / 迭代 / 设计报告，涉及架构、模块、调用关系、控制流、数据流的变更，要决定怎么把「改了什么」可视化。

不用：纯指标 / 性能 / 成本对比（用表格，图会损精度不增洞察）；纯配置 / 参数变、不改结构（用 diff 代码块 + 旧值→新值表）；trivial 单文件改动；无结构变更的纯文字调研报告（那归 workflow_analytical_writing）。

核心原理（grounded，不是审美偏好）

四条都来自仓库蒸馏的书，是「为什么这样画」的根。

变更在边不在点（Thinking in Systems AX_02，rules/skills/drafts/thinking_in_systems/codex_v6/axioms/）：要解释系统行为先找反馈回路而非单次事件。一次架构变更的本质不是「把节点 A 换成 B」，而是切断 / 接入了哪条回流、改了哪个流向、动了哪个控制点。所以 before/after 图要标注的是连接、流向、反馈环的变化，只标节点增删读者看不见行为为什么不同。典型：before 是开环无误差信号、after 引入 gate 闭合一个平衡回路，这条新回路才是变更本质。

先认出再理解（Sciences of the Artificial AX_13/AX_15，.../sciences_of_the_artificial/opus_v6/axioms/）：状态描述回答「它是什么样」（蓝图、拓扑），过程描述回答「它怎么运转」（流程、时序），两者互补不可互相还原。读者要先能「认出」新系统（状态图：before/after 拓扑对比），再能理解它「怎么动」（过程图：流程 / 时序对比）。缺状态图＝知道步骤不知结果长什么样；缺过程图＝知道目标不知怎么到达。选图就是在这两类描述里挑一种，混在一张图里画是反模式。

首屏决定去留（Information Foraging AX_03，.../information_foraging_theory/codex_v6/axioms/）：读者按信息气味在进入内容前就判断值不值得读；弱气味让人过早切换走（直接去问 AI）。before/after 图是最强的近端气味。所以首屏放一张图加一句判决，读者 30 秒判断，而不是先铺三段背景。

单一顶层主张（The Pyramid Principle AX_01，.../pyramid_principle/kimi_v6/axioms/）：画图前先写出这次变更的单一顶层主张（一句话：改了什么、影响是什么）。写不出，说明变更没想透，先别画图——图是思考的试金石，画 before/after 时画不清 before 态，正暴露文字藏住的模糊。

怎么做（结果导向）

判何时画：非平凡的结构 / 流向变化→画；纯指标→表；纯配置→diff（见「何时用 / 不用」）。

look-back 取证再画（承重，最易漏）：先从 Loop / run 记录 / commit / 聊天记录里还原真实的 before 态和每个 delta，再画。不凭记忆或想象画结构。每个 delta 锚一条真实证据（commit hash / file:line / run 记录）。取证不足以还原 before 态时，在报告里标这条边界，不编造结构填空。这一步和「画图」是连体的，拆开做等于只做一半。

选图（Simon 状态→过程，决策表）：

变更类型	核心问题	画什么
模块拆分 / 合并、依赖增删、层级重组	谁跟谁的关系变了	before/after 拓扑对比图（状态）
调用顺序、引入异步 / 队列、状态机变化	信号怎么流	before/after 时序 / 数据流图（过程）
结构 + 流程都变	两个问题都有	两图，先状态后过程，中间一句话衔接
指标 / 性能 / 成本	变了多少	表格（多维可比值），不画图
仅配置 / 参数	改了哪个值	diff 代码块 + 旧值→新值表

画什么（视图 + 语义）：节点 / 边语义和 mermaid 模板见术 skill bestpractice_markdown_report。视图选 Module（谁跟谁的依赖 / 调用关系，回答变更扩散到哪）或 C&C（运行时数据怎么流），两到三张，不强求做满也不停在一张总图（Software Architecture in Practice document-small-view-bundles）。图的粒度跟读者走：给决策者画到组件级，给接手工程师画到接口级（tailor-docs-to-readers「了解你的读者」）。

组织报告：首屏放 before/after 图 + 一句判决结论（非背景铺垫）；一级标题写成判决句（「认证层迁到 Gateway 后延迟降 85%」）而非分类标签（「架构说明」）；过程叙述（「我们尝试了……后来发现……」）压到附录或 <details> 折叠，正文篇幅权重对齐信息重要性（Sense of Style AX_34：篇幅即读者印象权重）；每张图配一句结论性图说指明「请读者看什么」（The Craft of Research AX_19）。

验收标准（无上下文 agent 可自判，也是 RC5 检测器的判据）

V-01 首屏价值：首屏（无需滚动）有 before/after 图 + 一句判决结论，不是只有背景文字。
V-02 同框可比：before 和 after 同布局 / 同框，颜色只标 delta（不变的用灰），眼睛平移就能找差异。
V-03 delta 标判决：每个变更点有就近 callout，文字是判决（新增 / 删除 / 合并 / 替换 / 反转）不是描述（「此处为 X」）。
V-04 delta 锚证据：每个 delta 能追到真实证据（commit / file:line / run），无编造结构。
V-05 图说是结论：图说指明看什么、关键变化在哪，不是「新旧架构对比」这种描述。
V-06 选图匹配：结构变更用拓扑图、流程变更用流程图、指标用表，没有把拓扑和时序混画在一张图里。

收口跑 check_report_completeness 的 RC5（确定性壳验 before/after mermaid 块在场 + regulator 判是不是同一对象的真 before/after、delta 有没有标注且锚证据），FLAG 按可定位反例改，别拿自评当数。

配套与跨域

道层：COMMUNICATION.md（去 AI 味，always-on，本 skill 不重述语言纪律）。
术层：bestpractice_markdown_report（before/after mermaid 模板 + 三色 classDef + 节点边语义 + 降级兜底）；要富交互 HTML（注释 / dark mode）走 bestpractice_final_report。
确定层：check_report_completeness 的 RC5（共生检测器：确定性壳 + regulator 给可操作反例），工具路径查 tools/INDEX.md。
元路由：workflow_report_writing_matrix 的可视化维度先指到这里。
内容轴邻居：bestpractice_report_readability（变化记录四件事 + look-back 自检）。
真源书（选图与组织原则）：Sciences of the Artificial AX_13/AX_15、Thinking in Systems AX_02、The Pyramid Principle AX_01、Information Foraging AX_03、Software Architecture in Practice（视图）、Sense of Style AX_34，蒸馏产物在 rules/skills/drafts/<book>/。

诚实 claim ceiling / 缺口

证据等级 bounded：本 skill 是设计综合（基于上述书的可引用原则 + 仓库现有报告体系 + 一个 before/after mermaid 孤例范本），未经多份真实报告 runtime 验证。「一张 before/after 图是否真降低读者理解成本」目前是假设，晋级需在 ≥1 份真实变更报告上 dogfood、过 RC5、且无背景读者只看图能复述变更。
选图决策表是默认启发，边界情形（既非纯结构也非纯流程的混合变更）靠 look-back 后的判断，不机械套表。
look-back 取证在某些报告上可能不可满足（run 记录不足以还原 before 态），此时标边界不编造，是诚实降级不是失败。

← 返回道层 skill 索引 · 返回方法论区