improve-pipeline

改进流水线

当实际使用流水线时发现流水线本身存在弱点，请使用此技能。触发事件可能发生在其他仓库中，但改进目标始终是 chrislacey89/skills：这些技能、文档、检查清单和工作流指南塑造了未来的智能体开发。

这不是自动自我修改。默认产出是在 chrislacey89/skills 中创建一个 GitHub issue。issue 应说明发生了什么、为什么这是流水线问题而不只是项目问题、建议做出哪些更改、这些更改可能对整个仓库产生什么影响，以及如果建议获批，需要修改 chrislacey89/skills 中的哪些文件。

如果用户在审阅提案后要求实施，可以将实施作为单独步骤进行。不要跳过提案。

每轮只问一个问题。 如果缺少关键信息，一次只问一个问题，并等待用户回答后再问下一个。切勿把事件收集或审阅变成问卷。

优先使用单选。 当用户需要选择一个方向、一项优先事项或一个下一步时，使用单选题。

谨慎使用多选。 仅用于彼此兼容、可以同时成立的选项集合——目标、约束、非目标、成功标准。如果涉及优先级，应接着询问用户选中的项目中哪一项最重要。

平台提供提问工具时优先使用。 在 Claude Code 中使用 AskUserQuestion；在 Codex 中使用 request_user_input；在 Gemini 中使用 ask_user。否则，在聊天中列出编号选项，并等待用户回复后再继续。

调用时机

这是一个可选的元技能，不是默认流水线阶段。

当主要经验教训与流水线本身有关时，使用 /improve-pipeline：

• 技能边界不清晰，导致了返工
• 交接产物缺失、质量不足或容易误导
• 某项防护措施或检查清单本应避免本可避免的失败
• 重复出现的失败模式表明流水线定义不够完善
• 某个提示词、工作流或仓库规范导致了过度拟合或浅层审查
• /compound 或 /pre-merge 发现的经验教训应归入流水线仓库，而不是下游应用仓库

如果经验教训主要与下游仓库有关，则不要使用此技能：

• 特定于项目的架构决策
• 特定于应用的 bug 修复
• 未暴露流水线弱点的库集成问题
• 应归入该仓库 docs/solutions/ 的可复用产品或领域知识

/compound 和 /pre-merge 可以建议使用 /improve-pipeline，但仅限于该技能已存在且主要经验教训明确属于流水线层面。不要自动调用。

存在原因

如果交付流水线从不从实际使用中吸取经验教训，最终就会针对提示词中想象的环境进行优化，而不是针对它实际运行的真实环境。最危险的流水线故障未必是明显的语法错误——它们可能是边界定义不清、反馈循环缺失、指南重复，以及单独看来逻辑连贯、端到端运行时却会失效的工作流步骤。

此技能旨在有意识地闭合这一反馈循环。它将现场事件转化为针对整个仓库的提案，而不是局部补丁。它的职责不是维护当前流水线，也不是冲动地修改流水线，而是弄清楚发生了什么、检验建议的更改能否推广，并产出能增强整个仓库的最小化协调改进。

执行流程

阶段 0：确认目标仓库并加载权威上下文

GitHub 问题的目标始终是 chrislacey89/skills。切勿根据当前工作区、下游项目的 git 远程地址，或事件发生所在的仓库推断其他目标。

在分析事件或提交任何内容之前，先加载 chrislacey89/skills 的最低限度权威上下文。在 skills 仓库内工作时，阅读仓库根目录中的原始文件；从下游项目调用时，阅读此技能旁边附带的副本：

• README.md — 快速了解 Skill Kit 是什么（仅仓库内提供；不随包附带）
• references/SYSTEM-OVERVIEW.md（或仓库根目录中的 SYSTEM-OVERVIEW.md）— 流水线理念、状态模型和交接方式
• CLAUDE.md — 编辑此仓库本身时的规则（仅仓库内提供；不随包附带）
• references/skill-anatomy.md（或仓库根目录中的 docs/skill-anatomy.md）— 技能变更的质量标准
• references/writing-for-humans.md（或仓库根目录中的 docs/writing-for-humans.md）— 问题正文的通俗易懂的讲解结构和修订标准

然后阅读：

• 与事件最密切相关的技能
• 边界有重叠的相邻技能
• 编码了相同指导内容的任何共享清单、模板或仓库文档

继续之前，先建立一份简短的上下文摘要：

• 此仓库的用途
• 此工作流中的状态存放位置
• 提议的变更最可能影响哪些仓库区域
• 变更合并后哪些内容应保持稳定

使用明确指定目标仓库的 GitHub 命令：

gh repo view chrislacey89/skills
gh issue list -R chrislacey89/skills --limit 1

如果无法确认对 chrislacey89/skills 的 GitHub 访问权限，或无法加载足够的权威上下文来整体判断该仓库，请停止并询问。不得将问题提交到下游仓库作为替代方案。

阶段 1：记录实际发生的事件

从实际事件出发，而不是从偏好的修复方案出发。

记录：

1. 事件发生的位置 — 仓库、分支、功能或工作阶段
2. 运行了哪条流水线路径 — 例如 /shape → /research → /write-a-prd → /execute → /pre-merge → /compound
3. 预期情况 — 流水线本应支持或防止什么
4. 实际情况 — 困惑、返工、分类错误、产物缺失、审核不充分、指导相互矛盾等
5. 有哪些下游证据 — PR、问题、失败的运行、反复出现的问题或具体示例

简明梳理运行过程：

• 哪个步骤引入了问题
• 哪个步骤未能发现问题
• 哪个步骤放大了问题
• 实际造成了什么代价：返工、错误指导、范围偏移、虚假信心、遗漏边缘情况或用户困惑

不要假定最显眼的故障就是流水线问题的根源。将事件与导致事件的结构区分开来。将事件描述为设计缺陷，而非用户失误（Norman 的责任归因反转原则）——“我忘了做 X”不是事件；“该技能让人很容易忘记做 X”才是。

阶段 2：证明这是管道问题

在提出任何仓库更改之前，先确认问题是否确实属于这里。

请问：

• 这主要是一个披着管道问题外衣的项目特定问题吗？
• 只改进下游仓库就能解决问题吗？
• 管道是否提供了错误的指导、缺失的指导、薄弱的步骤安排，或根本没有有效的防护？
• 这是一次性的异常，还是反复出现的问题？

对发现的问题进行分类：

• 局部事件 — 应由下游仓库处理，而不是这里
• 管道模式 — 由于同类问题很可能再次出现，此仓库应该做出更改
• 管道结构 — 问题源于缺少反馈循环、责任归属不明确、技能边界重叠，或仓库指导相互矛盾
• 冗余或适得其反的指导 — 已存在的文本，删除或整合后可以提升仓库的一致性。删减也是有效的发现，不只是新增内容。
• 伪装成纪律要求的修复方案 — 拟议的补救措施要求用户记住、留意或执行某些事情。将其重新归类为管道结构，并在添加说明文本之前，寻找一种将知识置于外部环境中的替代方案（默认行为、强制机制、结构性安排）。（Norman，外部知识与头脑中的知识。）

如果问题只是局部事件，请停止处理，并将其转交给下游仓库的常规文档流程或 /compound 流程。

阶段 3：扩大范围，审视整个仓库

切勿孤立地评估拟议的管道更改。

在建议编辑之前，检查所有可能受到影响的仓库内容：

• SYSTEM-OVERVIEW.md（如果在技能仓库之外调用，则检查 references/SYSTEM-OVERVIEW.md）
• 看起来与该事件最相关的技能
• 职责有重叠的相邻技能
• 其他位置承载相同指导的清单、文档或模板
• 如果更改会影响用户查找或调用工作流的方式，则检查 README 或其他介绍文档

请明确搜索：

• 可能因此变得不一致的重复指导
• 如果此更改落地，边界会发生变化的相邻技能
• 需要同步更新的提示词或模板
• 此更改会影响的仓库级术语
• 让管道变得更具规定性、更复杂或更有主张后可能产生的下游影响

只改进一个文件，却削弱仓库整体一致性的方案，还不能算准备就绪。

第 3.5 阶段：查阅图书馆

流水线提案应以既有的软件工程指南为依据，而不应只基于 Agent 或用户的观点。在运行辩论前，先查阅 /library——用户位于 ~/.claude/library/ 的本地图书索引——寻找与事件相关的书籍。

流程：

1. 浏览索引。 不带参数运行 /library 查看目录；如果事件有明确的主题入口（例如 testing、code review、debugging、systems、deep modules、feedback loops、refactoring、domain），则运行 /library --search <keywords>。
2. 选择 1–3 本相关书籍。 优先选择 description 或 tags 与事件类型直接相关的书籍。如果本技能的 sources: frontmatter 已引用相关书籍（Meadows、Duke、Senge、Nygard、Norman），则优先选择这些书籍，以保持技能的思想脉络与实际推理一致。
3. 加载书籍。 对每本选定的书运行 /library <name>，提取与事件相关的具体原则、检查清单条目或失效模式，并记录下来——这些内容将用于第 4 阶段和 issue 正文。
4. 适度查阅。 加载书籍会消耗上下文。除非事件确实涉及多个方面，否则最多查阅三本。
5. 妥善降级。 如果未安装 /library 或索引为空，则记录“图书馆查阅：不可用”，然后继续。不要因此阻止提交 issue。

每本加载的书都应为辩论提供可具体引用的内容——例如某项命名原则（“浅模块的异味”）、检查清单条目（“审查者检查 X”）或已知失效模式（“政策阻力”）。如果一本书没有提供可引用的内容，就从记录中移除，不要只提书名。

第 4 阶段：运行三方辩论

在撰写提案前，采用结构化的对立模式。在同一条消息中启动倡导者和质疑者两个子 Agent，让两者各自撰写开篇论点，且不受对方内容影响——同时形成的两份论点无法相互锚定，只有在彼此独立形成后再权衡才有意义。两者返回后，再由调解者介入。

如果无法使用子 Agent，则按顺序模拟这些角色，并在 issue 正文中将本次运行标注为降级模式：质疑者在撰写前会读到倡导者的论点，因此其独立性已不复存在，判决也应据此解读。降级模式下没有子 Agent 可回复，因此不会进行下文所述的回复轮次。

随后，调解者可以发起一轮回复——详见下方的判定条件。在同一条消息中发送两份回复，以确保回复也遵循开篇论点所要求的独立性。每份回复都要引用其回应的具体论点，说明认可哪些内容、哪些观点仍然成立，并控制在 250 词以内。角色不必达成一致；目标是得出正确答案，而非胜出（Liang 等人，Multi-Agent Debate）。

如果某条回复在没有引用论点的情况下表示让步，则舍弃该回复，并依据最初的两份论点作出裁决，同时在判决中注明该回复已被舍弃。附和式回复正是本轮最可能出现的失败，而且看起来恰恰像一条不错的回复（Du 等人将其称为迎合：Agent 指出同伴的错误，之后却依然采纳了该错误）。

Agent 1：倡议者

倡议者要为这项变更提出最有力、出于善意的论据。

倡议者应回答：

• 正在解决什么流水线问题？
• 为什么当前仓库无法解决这个问题？
• 哪项改进可以减少未来的故障？
• 为解决这个问题，应删除或合并哪些指令、章节或技能（如果有）？删减是优先考虑的选项，而非退而求其次。
• 为什么提出的变更比维持流水线现状更好？
• 具体可能需要修改哪些文件或技能？

倡议者必须引用至少一项支持这项变更的已加载库资料——可以是明确命名的原则、检查清单条目或设计指南。如果所调查的资料中没有任何书籍支持这项提议，就要明确说明；缺乏支持本身就是一种信号，不应掩饰。

Agent 2：质疑者

质疑者要为反对这项变更提出最有力、出于善意的论据。

质疑者应留意：

• 将流水线过度拟合到某个单一事件
• 重复其他地方已有的指导
• 技能之间的边界被侵蚀
• 意外增加复杂性或流程
• 给并非打算改进流水线的普通用户带来负担的建议
• 有证据表明问题出在下游，而非当前结构
• 增加了一项功能，成本却由今后的每位用户承担（Norman 所说的功能膨胀，与 Meadows 所说的政策阻力相结合）

质疑者必须引用至少一项资料来源或公认原则，该来源警示不要进行这项变更，或指出这项变更可能造成的已知失效模式（例如，Nygard 关于意外耦合的论述、Meadows 关于政策阻力的论述、Ousterhout 关于浅层模块的论述、Fowler 关于过早抽象的论述）。

Agent 3：调解者

调解者综合双方观点，并决定什么最有利于整个仓库。

撰写裁决前，须将每个决定性观点归因于双方其中一方案例中的引文。如果某个决定性观点在双方案例中都没有出处，或双方对可核实的事实相互矛盾，就进行回复轮次；否则，记录无需回复轮次并作出裁决。归因是把关机制，因为调解者若自行提出论据，就不会察觉这一点。

调解者应给出以下四种裁决之一：

• 拒绝 — 这不是流水线问题，或者所提修复会损害一致性
• 暂缓 — 方向值得考虑，但需要更多证据或更广泛地审查仓库
• 有限推进 — 实施小范围的针对性变更，控制影响范围
• 全面推进 — 多个产物必须保持同步，因此有必要更新整个仓库

调解者必须说明：

• 最小且完整的变更集
• 整个仓库面临的风险
• 明确保留不变的内容
• 未来有哪些证据可以作为重新审议决定的依据

调解者必须协调倡议者和质疑者引用的资料来源。如果双方引用同一本书却得出相反结论，就应在裁决说明中指出这种张力，而非悄然消解——对同一来源的原则性解读出现分歧，是能为未来审阅者提供参考的有用信息。

阶段 5：搜索相关议题，然后提交 GitHub 议题

在提交任何新议题之前，先搜索 chrislacey89/skills 中的相关议题。

gh issue list -R chrislacey89/skills --search "<keywords>" --state all

• 使用流水线领域、技能名称和事件中最明确的故障模式关键词，搜索未关闭和已关闭的议题。
• 如果已有议题涵盖同一问题，请更新或评论该议题，而不是提交重复议题。
• 如果已有议题相关但问题不同，请提交新议题并交叉链接两者。

完成重叠检查后，才将提案作为 GitHub 议题提交到 chrislacey89/skills。

gh issue create -R chrislacey89/skills

使用简洁的议题标题，指出流水线领域和改进机会。

建议的标题格式：

[improve-pipeline] <short summary of pipeline change>

示例：

[improve-pipeline] Clarify execute skill boundary for behavior-heavy frontend work

## Field Incident 和 ## Why This Is a Pipeline Problem 两个部分以通俗易懂的方式讲述此产物的来龙去脉——六个月后打开该议题的读者，无需打开下游仓库，也应能了解发生了什么以及为何重要。请遵循 references/writing-for-humans.md（与此技能一同打包）中的结构和修订要求：用用户自己的话交代领域背景，开篇直接点明要旨，说明每项建议变更的动机，并加入 **Why it matters:** 提示语。分析部分（## Advocate Case、## Skeptic Case、## Mediator Verdict）与事件说明并列，保持为简短要点或短段落——不要再写一遍事件说明。

编写 Recommended Changes 表格之前。 对于每一行中带有目标文件的条目，都要打开文件并确认其中存在所提议的结构——如果某行写着“在 Quick Reference 表格中添加一项”，那么只有目标文件确实包含 Quick Reference 表格时才有效。应在同一次阅读中决定内容和位置，而不是分两次处理。对于新增技能且打包了以 docs/ 为根目录的参考文件的提案，表格中必须包含 scripts/skill-references.manifest 条目，以及 SKILL.md 和发现文档条目；CLAUDE.md § 共享参考文件中规定的打包参考文件不变量要求如此，否则提交时 scripts/sync-skill-references.sh --check 将失败。

使用以下议题正文模板：

**Target repo:** chrislacey89/skills
**Date:** YYYY-MM-DD
**Status:** proposed
**Triggering repo:** <repo-name>
**Triggering context:** <feature, issue, or branch>
**Pipeline area:** <skill, doc, checklist, or repo-wide>
**Change type:** prompt | workflow | checklist | artifact | terminology | boundary | other
**Confidence:** low | medium | high

## Field Incident

[What happened in the downstream repo. Keep this factual and concrete.]

## Pipeline Run Breakdown

- **Path run:** [/shape → /research → ...]
- **Expected behavior:** [What the pipeline should have enabled or prevented]
- **Actual behavior:** [What actually happened]
- **Introduced at:** [Where the weakness entered]
- **Missed by:** [Which step failed to catch it]
- **Cost:** [Rework, confusion, false confidence, missed edge case, etc.]

## Why This Is a Pipeline Problem

[Explain why this belongs in the pipeline repo rather than only in the downstream app repo.]

## Repo-Wide Context

[List the repository areas reviewed and what each implies for the proposal. Include the canonical docs plus the closest affected and adjacent skills.]

- `path/to/file` — [Why it matters]
- `path/to/other-file` — [Why it matters]

## Library Consultation

- **Books surveyed:** [brief notes from `/library` index or `/library --search <keywords>`, or "Library consultation: unavailable"]
- **Books loaded:** [names of books loaded via `/library <name>`]
- **Key principles applied:** [1–3 bullets, each tied to a specific book and the concrete idea borrowed]

## Suggested Further Reading

**From the library** (already available via `/library <name>`):

- `<book-name>` — [one line on why this book is worth loading before implementing or reviewing this proposal]

**Gap in the library** (not yet available; worth acquiring):

- `<Title> — <Author>` — [one line on why this book would have sharpened the analysis and what topic area it fills]

If no gap is identified, remove the Gap subsection rather than leaving a placeholder.

## Advocate Case

[The strongest argument for making the change.]

**Reply:** [The Advocate's answer to the Skeptic. Omit when no reply round ran, or when the reply was discarded.]

## Skeptic Case

[The strongest argument against making the change.]

**Reply:** [The Skeptic's answer to the Advocate. Omit when no reply round ran, or when the reply was discarded.]

## Mediator Verdict

**Verdict:** Reject / Defer / Proceed narrowly / Proceed broadly

[The synthesis. State the minimal coherent change set and the key repo-wide tradeoffs. When the dialectic ran in degraded mode, say so here and say what it cost: the Skeptic read the Advocate's case before writing, so the two positions are not independent and the verdict should be read accordingly.]

## Recommended Changes

| Target file | Change type | Change | Why | Risk if skipped |
|-------------|-------------|--------|-----|-----------------|
| `path/to/file` | add \| modify \| remove \| consolidate | [Specific recommendation] | [Rationale] | [Consequence] |

For any `remove` or `consolidate` row, add a `Text removed (with location):` line directly under the row quoting the exact text being cut and the section it lives in. This prevents Chesterton's-fence deletions and gives reviewers something concrete to evaluate.

## Non-Goals

[What this proposal intentionally does not change.]

## Follow-On Options

- **Proposal only:** stop here and review the issue
- **If approved:** implement the recommended file changes in a separate step in `chrislacey89/skills`

## Related Evidence

- [Link to issue, PR, transcript excerpt, or prior proposal]

不要用空话充实各个部分。如果某个部分没有实质内容，就精简提案，而不是填充套话。

如果仓库中已有用于维护或流水线工作的标签，请添加相应标签。如果没有，不要因此耽搁。

如果提案的“Gap in the library”小节提到图书馆应购入的一本或多本书，请添加 library-gap 标签，让这些议题汇集成可见的待办列表，而不是埋在议题正文中。如果 chrislacey89/skills 中尚无此标签，请创建一次：

gh label create library-gap -R chrislacey89/skills \
  --description "Proposal surfaces a book the /library should acquire" \
  --color BFD4F2

然后将其应用于当前及今后的议题。如果因权限或网络问题无法创建标签，不要因此耽搁提交——在议题正文中注明之后应添加该标签。

阶段 6：在开始任何实现之前进行审查

向用户展示提案，并逐个问题与用户审查。

最低审查流程：

1. 对事件的描述准确吗？
2. Mediator 的结论恰当吗？
3. 建议的变更集是否符合整个仓库的一致性？
4. 这件事应保留为议题，留待日后分流处理，还是你希望现在批准并继续实施？

在用户审查提案并明确要求实施之前，不要开始编辑流水线文件。

阶段 7：可选的后续实施

实施是可选的，绝非默认选项。

如果用户批准实施：

• 更新提案中列出的最小连贯文件集
• 编辑任何核心技能前，先搜索是否存在重叠的指导内容
• 确保所有已修改内容中的术语保持一致
• 优先采用能解决结构性问题的最小仓库改动
• 如果提案影响调用边界，则更新所有规定这些边界的相关技能

实施后，报告：

• 哪些文件发生了更改
• 哪些内容有意保持不变
• 未来哪些事件可以验证或证伪此次改进

验证

只有满足以下所有条件，运行 /improve-pipeline 才算完成：

• 明确将目标仓库视为 chrislacey89/skills
• 已从 README.md、SYSTEM-OVERVIEW.md（或 references/SYSTEM-OVERVIEW.md）、CLAUDE.md、docs/skill-anatomy.md（或 references/skill-anatomy.md）以及 docs/writing-for-humans.md（或 references/writing-for-humans.md）加载规范上下文
• ## Field Incident 和 ## Why This Is a Pipeline Problem 部分符合 references/writing-for-humans.md 中规定的演练结构和修订标准
• 已审查最接近受影响的技能及相邻的重叠技能
• Advocate 和 Skeptic 在同一条消息中启动，且双方都没有收到对方的论据；或者，已提交的问题将此次运行标记为降级模式
• 问题记录了回复轮次的结果，且必须恰好为以下之一：保留回复（回复出现在两个论据章节下）、丢弃回复、无回复轮次（未触发门槛）或降级模式（没有子 Agent 可回复）。判断该轮次是否值得保留时，只有无回复轮次才算门槛未触发
• 已调查 /library（或记录其不存在），且所有已加载的书籍均在问题的 Library Consultation 和/或 Suggested Further Reading 下引用
• 提交或更新前，已搜索 chrislacey89/skills 中的相关问题
• 已在 chrislacey89/skills 中提交或更新问题，或者有意暂缓提交并说明了原因
• 如果提案建议删除或合并，问题中引用了要删除的确切文本，并说明其为何已变得冗余或适得其反

仓库级防护原则

• 让提案以既有指导为依据。 提交问题前，先查阅 /library 中与事件类型相关的书籍，并在 issue 中说明它们提供了哪些依据。如果 /library 不可用，请明确记录这一点，而不是悄悄跳过这一步。
• 先提案。 不要从事件直接跳到修改仓库。
• 避免过度拟合。 一次令人头疼的事件是证据，但不是定论。
• 保护普通用户。 大多数流水线用户是想交付工作，而不是改进流水线。
• 编辑前先搜索。 如果建议涉及某项技能，先检查相邻技能和共享文档，再进行更改。
• 明确影响范围。 每项提案都应说明会影响哪些文件、技能或约定。
• 优先采用最小且完整的修复方案。 避免借机大幅重写流水线。
• 考虑删减。 如果问题在于指导内容重复、矛盾或价值低，正确的做法是删除或整合，而不是再添一条。过去调用此技能时，方案严重偏向增加内容；只要证据支持，就应将删减视为同等重要的结果，并要求其证据与新增内容同样充分。
• 将项目知识留在项目中。 如果经验教训属于下游应用仓库，就按照该仓库的常规文档流程处理。
• 在 GitHub 中记录发现。 默认产物应为 chrislacey89/skills 中的 GitHub issue，而不是本地提案文件。
• 不要相信当前工作区的远程仓库。 事件可能发生在下游仓库，但该仓库绝不是 /improve-pipeline 的 issue 目标。
• 要求具备权威上下文。 在审阅核心仓库文档和重叠技能之前，不要提交流水线改进 issue。
• 如果无法获取权威上下文或访问 GitHub，请停止并询问。 不要猜测，也不要以其他位置作为替代提交目标。

此技能不是什么

• 不是 /compound。 /compound 为下游项目记录长期知识；/improve-pipeline 则为此流水线仓库记录改进事项。
• 不是自动自愈。 它会建议经过审查的更改，并可选择实施；不会悄悄修改流水线。
• 不是追责。 它分析结构性原因及其对整个仓库的影响，而不是追究谁犯了错。
• 不是本地补丁机器。 未检查整个仓库的一致性之前，不应只“修复”某项技能。

交接

• 预期输入： 使用流水线时遇到的真实事件或反复出现的阻碍，通常是在 /compound 或 /pre-merge 过程中发现的
• 产出： 在 chrislacey89/skills 中创建一个 GitHub issue，记录改进提案及其分析依据
• 后续可进行： 在提案获批后，于 chrislacey89/skills 中实施
• 建议来源： 当 /compound 或 /pre-merge 可用，且主要经验教训涉及流水线层面时，应由它们推荐此技能