菜单
在用户已经完成一次 implementation 工作后，把项目里的 implementation plan + git diff/log 渲染成一份单文件 HTML 实施报告。报告包含 TL;DR、风险概览、架构图（mermaid）、Before/After 数据流、决策记录卡片、风险清单。用于开会前快速对齐团队、向 reviewer 解释设计决策、归档实施叙事。当用户说"生成实施报告"、"impl-explain"、"explain implementation"、"展示这次实施方案"、"做一份 HTML 实施总结"时调用本 skill。
默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。
决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
直接命令不会经过审查 Prompt；运行前请先检查来源。
npx skills add https://github.com/tt-a1i/impl-explain --skill impl-explain命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
正在显示 SKILL.md
基于 SOC 职业分类
| name | impl-explain |
| description | 在用户已经完成一次 implementation 工作后，把项目里的 implementation plan + git diff/log 渲染成一份单文件 HTML 实施报告。报告包含 TL;DR、风险概览、架构图（mermaid）、Before/After 数据流、决策记录卡片、风险清单。用于开会前快速对齐团队、向 reviewer 解释设计决策、归档实施叙事。当用户说"生成实施报告"、"impl-explain"、"explain implementation"、"展示这次实施方案"、"做一份 HTML 实施总结"时调用本 skill。 |
把一次实施任务的方案叙事整理成单文件 HTML 报告。代码细节不在范围内（reviewer 想看 diff 自己 git diff），重点是为什么这么做、考虑过什么、放弃了什么、留了什么坑——这些信息只存在于实施当时，错过就丢了。
仅在用户已经完成一次实施且希望生成可视化总结时调用。如果用户只是闲聊或实施还没做完，不要 auto-invoke。
按优先级查找：
git rev-parse --show-toplevel 之内，不得匹配 .env* / *.pem / *.key / id_rsa* / credentials* 等敏感模式，不得含 .. 段。任一不符合：停下来告诉用户并拒绝。docs/superpowers/plans/ 下日期最新的 .mddocs/plans/ 下日期最新的 .md*plan*.md 模式的最新文件多 plan 仓库交叉验证：如果目录里 > 1 个 plan，"日期最新"不够准。算法：
git log <base>..HEAD --format='%s%n%b' 收集 commit token set（按非字母数字切分，过滤停用词 + boilerplate 如 superpowers/tracking/plan/implementation，过滤长度 ≤ 2 + 纯数字）## TL;DR 段 + ## Decisions 的 ### 子标题）按同规则切 token找不到任何 plan：告诉用户先写一份再跑，停止。
git symbolic-ref refs/remotes/origin/HEAD --short 失败则 fallback main → mastergit log <base>..HEAD --format='%h %s' --no-merges
git log -10 --no-merges 取最近，让用户确认哪几条属本次"<first> .. <last> (N commits)" 一行git diff <base>..HEAD --name-status（只用来理解范围，不嵌进 HTML）不需要中间 JSON，不需要外部脚本，直接生成单文件 HTML 写到 git rev-parse --show-toplevel / impl-explain.html（不在 git repo 时落 CWD 并显式告诉用户位置）。
视觉参考：本 skill 目录下的 examples/sample.html 是一个完整渲染好的样例。
硬约束（必读 + 必做）：
<style> 块、<script> 块、以及顶部 sticky TOC / progress bar / hero / TL;DR-risk-tail / decision card / risk-snapshot / risk-highlight / out-of-scope 这 8 个结构片段<style>...</style> 和 <script>...</script> 整段原封不动拷到你生成的 HTML，只改 <body> 里的内容。不要尝试"挑出几个色 token 自己写 CSS"——团队跨报告一致性 > 单次创意。换风格的方式是单独换 sample.html，不是每次 freestyle<script> 块开头（mermaid.initialize 之前），sample.html 里已经有，你按上一条 verbatim 复制就自动带过来；但你单独检查一遍：// 安全前导：data-content 里 mermaid 源是 HTML-escaped 的，先 textContent 解码再交给 mermaid
(function () {
document.querySelectorAll('.mermaid[data-content]').forEach(function (el) {
el.textContent = el.dataset.content;
el.removeAttribute('data-content');
});
})();
漏掉这 8 行 + 配套 htmlLabels:false = mermaid 节点 label 里的 <script> / <img onerror> 直接 XSS。这是 v1 修过的真实 P0 安全漏洞，v2 lite 不能 regress。
data-content 属性——具体形式：<div class="mermaid" data-content="flowchart LR A --> B classDef newcomp fill:#fbeede class A newcomp"></div>
不要直接 <div class="mermaid">flowchart LR ...</div> 把源码塞进 innerHTML。
写入方式：先写临时文件再 rename（原子写入），避免中断时留半成品 HTML。
告诉用户绝对路径 + 简短摘要（N decisions / N risks / N high）+ "双击即可在浏览器查看"。
下面的段不必都出现——plan 里没素材就跳过整段，不要硬凑节点 / commit list / 文件清单充数。叙事密度 > 信息覆盖度。
47 → 1 loops、4 sources unified）。不要堆 6/5 这种 decisions/risks 计数 chip——那是 section meta 的事三行：做什么 / 怎么做 / 代价。
5 risks · 1 high (已缓解) · 看详情 →）classDef newcomp fill:#fbeede,stroke:#b04a1f,color:#1f1c17,stroke-width:1.5px + class A,B,C newcomp 高亮style X fill:#暗色——会跟浅色主题打架两张并排 mermaid。flowchart TB 通常比 LR 排版更稳（cell 高度更均衡）。
chosen（采用一句话）/ rationale（理由 2-4 句）/ rejected（放弃的备选 list）/ cost（局部代价）/ status（chosen 或 deferred——没有 rejected，被全否决的决策放进 Out of Scope）5 risks · 1 high · 2 medium · 2 lowseverity (low/medium/high) + description + 可选 italic note + mitigation (full/partial/none) 标签mitigation 同义词速查（避免误判）：
partial：note 含 future / 后续 / 后期 / 长期 / TODO / 暂未 / 未接入 / 上线后 / 已沉淀 / 需补none：未做 / 尚未观测 / 未来加 / 计划中 / 暂时不做 / 待+动词（待评估 / 待补充）full：note 描述已经生效的具体阻断机制（启动校验、测试覆盖、flag 判断）partial，比 full 更诚实至少 1 条（validate 不再做硬卡，但 0 风险报告通常不真实——多副本部署 / 第三方依赖 / 静默失败 三类至少能想到一类）
故意没做的事，italic 列表。具体（"暂未做 leader election"）而非空泛（"未来可能优化"）。
唯一规则：完整 verbatim 复制 sample.html 的 <style> 和 <script> 块。
不要"挑几个 token 自己写"，不要"按记忆里 v1 的样子重写"，不要"加点新风格"——agent 没有"风格设计权"，只有"内容生成权"。换视觉只能改 sample.html 一份文件，从而让所有未来报告同步变。
下表只用来快速核对你复制过去的 CSS 还能找到这些 token（不是让你单独定义）：
背景: --bg #faf7f2 (warm cream) / --bg-card #fdfaf3
文字: --text #1f1c17 / --text-soft #4a443a / --text-muted #8a8275 / --text-faint #b8b0a0
强调: --accent #b04a1f (terracotta)
状态: --chosen #4a6a2c (olive) / --deferred #8a5a17 / --rejected #7a2f24
severity: high #7a2f24 / medium #8a5a17 / low #a89970
mit: full #4a6a2c / partial #8a5a17 / none #b8b0a0
字体: Fraunces (serif 标题) + Inter (正文) + JetBrains Mono (label) — Google Fonts CDN
mermaid: theme 'base' + 上面 token / fontSize 14 / htmlLabels: false
布局: max-width 760px, padding 64px 32px 120px, sticky TOC + 1px progress bar
如果你复制过去的 CSS 找不到上面任一 token，说明你没读完 sample.html——回去重读。
htmlLabels: false（节点 label 渲染为 SVG <text>）<div class="mermaid" data-content="ESCAPED"></div> 的 attribute 而不是直接 innerHTML，加一段 JS shim 在 mermaid.initialize() 前用 el.textContent = el.dataset.content 复制回来& < > " '）<script> <iframe> <object> 等危险标签到 mermaid 字符串里/impl-explain.html 或让用户自己决定）git diff --name-status