utility-pm-skill-iterate

PM 技能迭代

此技能通过应用你提供的针对性修改，改进现有的 pm-skills 技能。它会读取当前技能文件，按文件分组展示修改前后的预览，并在你确认后写入修改。应用修改后，它会建议版本升级类别，并询问是否更新 HISTORY.md。

迭代器接受以下任意一种输入：

• 来自 utility-pm-skill-validate 的验证报告
• 直接反馈（“模板缺少 X 部分”）
• 规范变更（“所有技能现在都需要「局限性」部分”）
• 一般改进请求（“让示例更贴近实际”）

适用场景

• 运行 utility-pm-skill-validate 并收到包含问题的报告后
• 对某项技能有具体反馈并想应用修改时
• 仓库规范发生变化，需要技能遵循新规范时
• 技能的示例、模板或说明需要改进时
• 发布前迭代技能时

不适用场景

• 从头创建新技能 → 使用 utility-pm-skill-builder
• 修改前审查技能 → 先使用 utility-pm-skill-validate
• 在多项技能中批量修改规范 → 先运行 utility-pm-skill-validate --all 进行分类，再逐次迭代一项技能

说明

收到迭代技能的请求时，请遵循以下步骤：

步骤 1：确定目标技能

接受以下任意形式的技能名称：

• 目录名：deliver-prd
• 完整路径：skills/deliver-prd/SKILL.md
• 斜杠命令：deliver-prd

解析为规范目录路径：skills/{name}/。

如果技能目录不存在，请停止并报告：“技能目录 skills/{name}/ 不存在。请使用 utility-pm-skill-builder 创建该目录。”

步骤 2：读取当前技能文件

读取技能目录中的所有文件：

文件	必需	用途
SKILL.md	是	Frontmatter 和说明（主要编辑目标）
references/TEMPLATE.md	是	输出模板
references/EXAMPLE.md	是	完整示例
HISTORY.md	否	版本历史（步骤 7 需要）

此时记录每个文件的确切内容。步骤 5 写入前，你需要将其与记录的内容进行比较（防止预览过期）。

如果无法读取文件（MCP/嵌入式环境），请让用户在继续前粘贴相关文件内容（参见降级模式）。

步骤 3：将输入规范化为预期修改

无论输入类型如何，在生成任何编辑内容前，都要提取一份结构化的预期修改列表。此规范化步骤能确保所有输入类型都采用一致的统一流程。

如果输入是验证报告（来自 utility-pm-skill-validate）：

• 检查报告头部是否包含 Report schema: v1。如果缺少或架构版本不同，请警告：“此报告使用了无法识别的架构。我会尽力处理，但可能会遗漏结构化字段。”
• 解析 ## Recommendations 部分。
• 按 | 拆分每条建议行，提取：
  • 位置 1：严重程度（FAIL、WARN、INFO）
  • 位置 2：检查 ID
  • Target: 之后：文件路径
  • 下一行 Action: 之后：要修改的内容
• 根据这些字段构建预期修改列表。

如果输入是自由文本（反馈、规范变更、改进请求）：

• 阅读输入并确定需要修改的内容。
• 将每项修改对应到具体的目标文件和章节。
• 如果输入含糊，只询问一个澄清问题，然后再继续。

向用户展示规范化后的列表以供确认：

Intended changes:
1. Target: skills/{name}/SKILL.md -> {section}
   Change: {what will change}
   Source: {validation report check ID | user feedback | convention change}
2. Target: skills/{name}/references/EXAMPLE.md -> {section}
   Change: {what will change}
   Source: {source}

如果用户想修改此列表（添加、删除或更改项目），请调整并重新展示，然后再继续。

第 4 步：预览拟议的更改

对于每项预期更改，生成拟议的编辑内容，并按文件分组，以更改前/更改后的区块呈现：

### skills/{name}/SKILL.md

**{Section name} -- before:**
> {exact current content of the section being changed}

**{Section name} -- after:**
> {proposed new content for this section}

### skills/{name}/references/EXAMPLE.md

**{Section name} -- before:**
> {exact current content}

**{Section name} -- after:**
> {proposed new content}

预览规则：

• 按文件分组显示所有更改。每个文件只显示一次，并包含该文件的所有更改。
• 显示足够的上下文，让用户理解更改。
• 对于较小的编辑（几行），显示更改前后的完整章节。
• 对于较大的编辑（重写章节的大部分内容），显示更改前的章节标题和开头/结尾的几行，然后显示完整的更改后内容。
• 不要显示未更改的文件。

询问：“应用这些更改吗？[yes / no]”

如果用户回答 no，询问需要调整什么，然后返回第 3 步或第 4 步。

第 5 步：应用更改（并防止使用过期预览）

写入任何文件之前，重新读取每个目标文件，并将其内容与第 2 步中记录的内容进行比较。

如果任何目标文件自第 2 步以来已更改：

• 不要写入任何文件。
• 报告：“文件 {path} 自生成预览以来已更改。 正在根据当前内容重新生成预览。”
• 使用相同的预期更改列表返回第 2 步。

如果所有目标文件都匹配：

• 将更改写入每个目标文件。
• 将 SKILL.md frontmatter 中的 updated 字段更新为今天的日期。（无论是否接受版本号升级，updated 字段都用于记录文件最后修改的时间。）
• **保留字节 0 位置：**确认每个重写的文件在字节 0 处仍为 ---（前面没有内容）。如果之前的内容不符合字节 0 位置要求（例如第 1 行有 HTML 署名注释），请在应用其他更改前谨慎指出，并提出将位置修正一并纳入本次写入。参考： library/skill-output-samples/SAMPLE_CREATION.md 第 5 节。
• 报告写入内容：列出每个文件，并用一句话概述更改。

第 6 步：建议版本升级

应用更改后，对整体更改进行分类，并建议版本升级类别。不要自动写入版本号。

分类规则（摘自 docs/internal/skill-versioning.md）：

更改类型	升级类别	示例
澄清措辞、改进示例、修正拼写错误	patch	重述检查清单项、改进示例场景、扩展描述
新增可选功能或章节	minor	新增可选输出章节、支持更多场景、新增质量检查
必需契约变更、交互模式出现不兼容变化	major	重命名命令、移除必需章节、缩窄“完成”的定义

**判断优先级：**如果用户必须采取新操作才能继续遵守该技能的必需契约，则归类为 major。如果新行为是补充性的或可选的，则归类为 minor。如果必需行为没有改变，只是得到澄清，则归类为 patch。

显示建议：

Suggested bump: {class} ({reason}).
Current version: {current}.
Bump to {suggested}? [yes / override / skip]

• yes：将新版本写入 SKILL.md frontmatter。
• override：询问期望的版本，验证其符合 SemVer 规范且高于当前版本，然后写入。
• skip：保持版本不变。用户之后可以在发布准备期间升级版本。

步骤 7：提供 HISTORY.md 更新选项

确定版本后，生成变更摘要，并根据当前状态处理 HISTORY.md：

如果 HISTORY.md 存在且版本已提升：

1. 阅读 HISTORY.md 并验证其格式：
   • 有一个摘要表格，表头为 | Version | Date | Release | ...
   • 表格中的版本按从新到旧排列
   • 表格中的每个版本在下方都有对应的 ## X.Y.Z 章节
2. 如果格式有效：询问是否追加。 “是否要将此版本添加到 HISTORY.md？[yes / no]” 如果回答 yes：在摘要表格中添加一行（按从新到旧排列），并添加一个包含变更摘要的 ## X.Y.Z 章节。
3. 如果格式无效：发出警告并显示拟添加的内容，不要 写入。“HISTORY.md 不符合预期格式。以下是拟添加的内容—— 你可以手动粘贴：” 然后显示拟添加的表格行和版本章节。

如果 HISTORY.md 不存在，且技能版本为 1.0.0 或更高： 无论此变更是否提升版本，文件都视为缺失。每个版本为 1.0.0 或更高的技能，从首个版本开始 都应包含 HISTORY.md （docs/internal/skill-versioning.md，“何时创建”）。询问是否创建。 “此技能没有 HISTORY.md。是否要创建？[yes / no]” 如果回答 yes：按照该文档规定的格式创建 HISTORY.md，并为技能发布时的版本添加基准行 （依据发布历史或工作简报）；如果此变更提升了版本，还要为新版本添加一行。

如果 HISTORY.md 不存在，且技能版本仍为 0.x：

• 如果此变更提升了版本（通常提升至 1.0.0）：询问是否创建 HISTORY.md， 并添加一行新版本记录，说明为何此时契约已稳定。不要补录 0.x 版本的记录。
• **如果此变更没有提升版本：**不询问。0.x 技能尚未形成契约， 其文件从首次版本提升时开始记录。

如果 HISTORY.md 存在但版本未提升（跳过）： 不询问。变更摘要已在对话中提供，用户可酌情使用。

步骤 8：汇报摘要

提供最终摘要：

## Iteration Complete: {skill-name}

**Files changed:**
- skills/{name}/SKILL.md -- {summary}
- skills/{name}/references/EXAMPLE.md -- {summary}

**Version:** {current} -> {new} ({class}) | or: unchanged (skipped)
**HISTORY.md:** updated | created | skipped | not applicable

**Next steps:**
- Run `utility-pm-skill-validate {name}` to verify the changes pass
- Run local CI: `bash scripts/lint-skills-frontmatter.sh`
- If satisfied, commit the changes

降级模式

如果你无法直接读取技能文件（例如通过 MCP 运行，或在无法访问文件系统的嵌入式环境中运行）：

1. 此模式下，优先采用由验证报告驱动的迭代方式。 报告包含上下文（检查 ID、目标路径、操作）。
2. 对于自由文本迭代，请用户粘贴每个相关文件的内容，再提出修改建议。
3. 无法执行过期预览检查（步骤 5）——请在摘要中注明： “已应用，但未进行过期预览检查（文件系统不可用）。”
4. 处理 HISTORY.md 需要用户粘贴当前文件内容，或确认该文件不存在。

输出约定

迭代器 MUST：

• 在编辑前将输入规范化为结构化的预期变更列表
• 按文件分组，以修改前/修改后的预览形式展示所有拟议变更
• 在写入任何文件前，要求用户明确确认
• 在写入前重新读取目标文件，以防预览过期
• 每次应用变更时更新 updated frontmatter 字段
• 建议版本提升类型，但不得自动写入版本号
• 按照步骤 7 中的规则处理 HISTORY.md

迭代器 MUST NOT：

• 未先展示预览就写入文件
• 未经用户确认就写入文件
• 未经明确确认就自动递增版本号
• 在此变更不提升版本时，为 0.x 技能创建 HISTORY.md
• 未先验证 HISTORY.md 格式就向其中追加内容

质量检查清单

完成本次迭代前，请确认：

• 编辑前已将输入规范化为预期变更清单
• 所有拟议变更都已通过修改前／修改后预览展示
• 写入任何文件前已获得用户确认
• 写入前已运行过期预览防护（或注明该功能不可用）
• 已将 SKILL.md frontmatter 中的 updated 日期设为今天
• 已根据正确的理由建议版本升级类别
• 仅在用户明确确认后才写入版本号
• 已按照第 7 步的规则正确处理 HISTORY.md
• 已提供最终摘要和后续步骤

示例

请参阅 references/EXAMPLE.md，其中展示了一个已完成的迭代示例：根据验证报告改进实际发布的技能。