用途:为一次代码变更撰写人类可读的记录,支持四种模式:pr(PR 正文)、changelog(变更日志条目)、release-note(发布说明)、postmortem(事故复盘)。核心规则是每句话都必须能追溯到本次调用中读过的 hunk 或 commit,记忆中的内容不算证据,diff 才算。
主要能力与用法:无参数时先查看仓库,再只问一个问题并给出推荐(推荐依据:有未提交 diff 或分支领先 base 选 pr;有 tag 但 docs/releases/ 无对应文件选 release-note;已合并工作缺失于 CHANGELOG.md 的 Unreleased 选 changelog;用户提到事故、中断或回归选 postmortem)。确定范围后必须实际读取,使用 git diff --stat <range>、git diff <range>、git log --format='%h %ad %s' --date=short --no-merges <range>、git log --format='%h %s%n%b' --no-merges <range> 等命令;大 diff 先看 --stat 再按路径逐区读取,绝不描述未读过 hunk 的文件。随后查找治理规范(projects/<name>/plans/*.md 或 README 映射指定的路径),匹配 AC 编号、已填的 Verified 单元格和 Non-goals;无规范或无匹配 AC 时写 no spec — n/a,不得编造。按模板起草,模板位于 ${CLAUDE_PLUGIN_ROOT}/skills/document/templates/<name>.md。
诚实规则:每个论断都要有证据指针(路径+改动或 path:line,或 commit sha);diff 未显示的内容不写;无来源的数字不写,禁止“更快”“性能提升”“更可靠”“更简洁”等无依据表述;未验证的保持“未验证”;失败、跳过的测试、新增 TODO、无证据的 AC 都要写入文档;人类告知的内容要注明来源;规范偏差要写入 Risks 或 Out of scope。
写入位置:pr 默认在对话中打印,用户要求文件时才写 .git/PR_BODY.md 并提示 gh pr create --body-file .git/PR_BODY.md;changelog 写入仓库根 CHANGELOG.md 的 ## [Unreleased] 下对应 Added/Changed/Fixed/Removed 子节;release-note 写入 docs/releases/<version>.md;postmortem 写入 docs/postmortems/YYYY-MM-DD-<slug>.md。若 README 映射或已有文件(如 docs/CHANGELOG.md、RELEASES.md)指定了位置,以既有约定为准,不创建第二个存放处。对已有文件的编辑要外科手术式,保留邻近文字、顺序和格式。
限制:不得编辑代码、测试或配置;不得编辑规范文件(projects//plans/.md);不得触碰 .claude/memory/MEMORY.md、context/handoffs/、projects/*/BACKLOG.md 或 findings 注册表;除非用户要求,不运行 git commit、git push 或 gh pr create;postmortem 中不得点名个人为原因,只写角色与系统。完成时输出四行摘要:Headline、Next、Heads up(无内容可省略)、Pointer。