chrislacey89/compound

compound 是做什么的？

记录最近解决的问题或已交付的功能，以积累项目的知识。每个记录的解决方案都会使未来的规划和实施更加快速——代理在执行 /research 和 /write-a-prd 时会查阅 docs/solutions/，因此今天学到的经验可以防止明天的错误。

如果工作中出现了规划或估算的意外，也要记录这些内容。McConnell 风格的校准只有在实际工作反馈回未来的规划中时才会发生。

调用位置

这是一个主要流水线技能，用于闭合知识积累循环。它在默认交付路径的末尾附近运行，在 /pre-merge 创建 PR 之后执行。

默认方式——在合并前捕获经验到 PR 中。 如果在 PR 阶段就已经知道可复用的经验，则在开放的 PR 分支上运行 /compound，使 docs/solutions/ 的条目与教会它的代码一起出现在同一个 PR 中——在合并前一起审查，并原子性地合并。这使 /compound 位于 /pre-merge 和 /closeout 之间，并返回通过 /pre-merge 一次：

… → /pre-merge → /compound（在 PR 内，当存在经验时）→ /pre-merge（重新运行：compound 提交是后添加的差异；重新添加标记）→ /closeout（合并 + 清理）→ 清理

返回步骤并非装饰。提交到分支会使 HEAD 移过 /pre-merge Phase 4 写入的标记，而 /pre-merge 是该标记的唯一写入者——因此如果没有重新运行，条目将与代码一起合并但无人阅读，这正是选择 PR 内默认方式所要避免的唯一情况。Phase 5 描述了交接；这正是其存在的原因。

备用方式——合并后捕获。 有些经验只有在合并期间或之后才会显现：集成中的意外、QA 发现、上线后观察到的行为。对于这些情况，在 /closeout 合并后运行 /compound。这是备用路径，不是默认路径。

无论哪种方式，/compound 从不执行合并或工作树清理——那是 /closeout 的任务——也从不写入审查标记，那是 /pre-merge 独有的。在 PR 内捕获意味着提交到开放的 PR 分支并交回以进行覆盖该提交的审查；它并不意味着合并。

不要将其用于琐碎修改，或用于应完全属于更高保真度工件（如测试、lint 规则或代码注释）且没有可复用的项目级学习的经验。无论是在 PR 内还是合并后，下面的“何时不使用”限制仍然适用——大多数 PR 不包含可复用的经验，也没有每个 PR 都必须填充的固定 docs/solutions/ 插槽。

为何存在

如果没有这一步，你只是在使用 AI 辅助进行传统工程。工作流的前三个步骤（规划、工作、审查）产生一个功能。而这第四步产生的是一个每次都能更好地构建功能的系统。

何时使用

• 当某个功能的 PR 就绪，且它教会了可复用的经验时——在合并前将其捕获到 PR 中（理想路径）
• 上线后，当经验只有在合并期间或之后才变得清晰时（合并后备用路径）
• 修复了一个棘手的 bug，其根本原因并不明显之后
• QA 周期揭示了本可更早发现的问题之后
• 做出了具有重大权衡的架构决策之后
• 发现了一个应被复用的模式之后

何时不使用

• 对于琐碎修改（拼写更正、简单配置更改）
• 当解决方案已在官方库文档中详细记录时
• 当经验是项目特定的，但你即将弃用该代码时
• 当工作是按预先制定的计划干净执行的——没有意外，没有返工，没有非显而易见的决策。问题描述和 PR 描述已经承载了这些记录；没有可复用经验的 docs/solutions/ 条目会训练未来的读者跳过它
• 当有疑虑时——跳过没有任何代价，因为问题和 PR 在 GitHub 中持续存在。而捕获一个低价值的经验会消耗未来规划者的注意力，每次他们查阅 docs/solutions/ 时都是如此

执行流程

Phase 1：识别要捕获的内容

在 PR 内默认路径中，待审查的工作是开放的 PR 分支，因此下面的命令直接读取它——git log 和 git diff 分支与将要合并的基础分支之间的差异，同时它尚未合并。在合并后备用路径中，在一个仍能看到已合并功能历史的会话中运行这些命令——一旦 /closeout 清理了分支并拉取了基础，该 diff 将为空，你必须改用 gh pr diff <n> 读取 PR diff。无论哪种方式，都要审查最近的工作。

首先解析基础分支。不要硬编码 main——这个仓库本身使用 prod，并且名称不是引用：在工作树工作流中，没有人检岀基础分支，因此本地分支在创建检岀时是冻结的，而 origin/<base> 在移动。询问 sidecar.sh base-ref；不要自行推导基础分支。

SC="<此技能目录>/references/sidecar.sh"
BASE_REF="$(bash "$SC" base-ref)" || { echo "base-ref 失败：不猜测基础分支" >&2; exit 1; }
git log --oneline "$BASE_REF..HEAD"
git diff --stat "$BASE_REF...HEAD"

查看：

1. Git 日志——提交了哪些内容？更改了什么？基于基础分支，而不是 -20：固定的计数会在比其短的分支上将基础分支本身的历史读取为“待审查的工作”。此处两个点是正确的——这些是此分支上而非基础分支上的提交。（git diff 使用三个点，原因对应：它从合并基础而不是减去基础分支方面的工作进行 diff。）在合并后备用路径中，分支已不存在，因此如上使用 gh pr diff <n>。

2. 问题线程——原始问题是什么？讨论了什么？

3. Diff——哪些文件更改了？出现了哪些模式？

询问用户：“你学到的最重要的东西，或者这个功能最棘手的部分是什么？”他们的回答常常揭示了最高价值的经验。

在写作之前，将经验分类到适当的级别：

• 事件——一次性的事件或可见的故障
• 模式——在功能、bug 或交接中反复发生的事情
• 结构——代码库、工作流、激励机制或决策过程中持续产生该模式的重复条件

优先捕获你能用证据支持的最高级别。如果经验是结构性的，则命名使其结果可能发生的反馈循环、缺失反馈或延迟效应。

在继续之前，回答四个问题：

1. 这真的是新的吗？ 检查官方库文档和 Phase 4 的重叠搜索覆盖的存储。如果经验已在其他地方充分记录，则跳过它或链接到现有来源。
2. 这三个月后仍然准确吗？ 如果经验与某个依赖版本或临时工作区解紧密耦合，则注明这一点——它影响下面的 volatility 分类。
3. 这个经验能否更靠近源头捕获？ 行为不变量更适合作为测试。惯例更适合作为 lint 规则。“为什么”的解释更适合作为与决策位置相同的代码注释——限定于当前的原因，即读者需要理解现有代码的原因。发现该问题的事件属于提交消息和 PR 描述，而重构历史的读者已经会查看这些地方；/execute 第 3 步在编写注释时指出了这一路由，而这个问题是在事后检查它。如果经验可以在更高保真度的工件中捕获，则这样做而不是编写散文。这关乎承载经验——Phase 4 的聚类检查问的是另一个问题，即机制是否应捕获下一个实例，而重复实例可能需要一个机制，即使经验本身需要散文。
4. 流程是否被修复？ （仅限 bug 修复的经验。）修复是更正（移除了缺陷）还是变通方案（抑制了失败）？代码库中其他结构相似的模式是否被找到并解决？什么流程更改可以防止此类缺陷再次进入代码库——更强的测试、lint 规则、断言、规划清单项，还是在 chrislacey89/skills 中提交的问题（参见下面的针对包提交）？如果答案是“什么都不需要”，那么产生此缺陷的机制仍然活跃。

针对包提交——第五种机制

此小节不限于 bug 修复。 上面的 Q4（其标题如此），但 Q4 和 Phase 4 的提升到机制规则都引用了下面的规则，而 Phase 4 不限于 bug 修复。此机制存在所针对的事件是一个功能经验。一个仅能从自身事件未采取的路径到达的过程正是正在修复的缺陷，降低一个级别——因此规则在此处声明一次，两个阶段都指向它们。

第五个名称的作用域由所有权限定，而非难度。 前四个是此代码库的工件；第五个存在是因为某些阻止性更改不是——它们是对 chrislacey89/skills 中技能的散文、门控、交接或契约测试的更改，而任何下游工件根本无法承载这些更改。只有在这种情况下，第五个名称才符合条件。它不符合条件是因为前四个很难、成本高或在此不明确：那正是合规出口 chrislacey89/skills#257 故意保持关闭的情况，而“我无法构建一个”仍然像以前一样解决——通过在条目中命名四个中哪一个最接近以及什么阻止了它。

提交所有者门控（务必确认——在写入任何输出前检查）

提交会将文字从你所在的仓库移到一个公开仓库。 这与列表中每个其他机制——测试、lint 规则、断言和清单项——都是不同的行为，这些机制都留在原地。因此，在组合正文之前，请确认当前仓库的所有者是你被允许从中提交的：

git remote get-url origin | sed -E 's#(git@[^:]+:|https://[^/]+/)([^/]+)/.*#\2#'

将其与下面的允许列表进行比较。允许列表是完整门控——不在列表中的所有者都不允许，包括你不识别的所有者。 不要将其反转成“阻止我知道是工作的所有者”：上周才上线的客户组织不在任何人的列表中，因此拒绝列表恰恰会接纳保密态势最不为人知的仓库。对未知者默认失败。

chrislacey89

该围栏周围的标记是承载性的：此小节包含多个围栏块，因此“列表是下面的代码块”对于任何机械读取的东西都是模糊的——一个猜测错误的读取器会提取散文，然后每个所有者都会失败检查。匹配标记，而不是位置。

仅作为经过深思熟虑、经过审查的编辑将所有者添加到该列表中——一行，离线，可搜索。你贡献的公开仓库在你命名该仓库后符合条件；它并不仅因其公开而符合条件。可见性是一个可变的远程属性，公开 fork 可以前置私有父仓库，而——这正是此处重要的原因——提交的内容是关于工作的叙述，而不是仓库的代码。公开源代码和围绕它的保密参与是常规组合，而“我们在为 Y 构建 X 时遇到了这个”即使每一行都是世界可读的也会泄露关系。

当所有者不在允许列表中时，第五个名称不可用。 回退到此机制之前的行为：将建议记录在条目的预防→流程级别插槽中，推荐 /improve-pipeline，并让人将其传递。经验不会丢失；只是不会自动传递。

组合和提交

当所有权守卫和提交所有者门控都通过时，提交是机制，而 /compound 执行它——到达此仓库的建议是工件，而不是推荐某人将其带到那里的句子。首先检查重叠并在现有问题上评论，而不是提交新的问题；新通道进入积压工作仅在它不会充满重复声明时才有价值。

gh issue list -R chrislacey89/skills --state all --search "<流水线区域> <故障模式关键词>"
gh issue create -R chrislacey89/skills --title "[improve-pipeline] <流水线区域> — <建议>" --body-file <file>

--title 和 --body* 是必需的，而非样式：gh issue create 在没有任何非交互式运行器（此机制旨在支持的所有 AFK 路径）的情况下会在没有它们时出错。

将正文匿名化编写，并将其视为契约的一部分而非礼貌。 上面的门控决定是否你可以提交；这个决定什么会跨越边界。描述事件的形式，而非其主题：

• 命名包文件更改的目标、错过它的流水线步骤，以及它本应做什么。
• 不要命名下游仓库、其所有者、其客户端、其路径、其标识符，或其问题和 PR 编号。描述其特征——“一个下游 TypeScript Web/页面分析仓库”——就像 chrislacey89/skills#266 所做的，这是一个工作示例：它开头为 触发仓库：匿名化 并记录来源是故意去除了标识符。
• 不要引用此条目的路径作为证据。 docs/solutions/… 路径是读者可能无权访问的仓库中的文件名，因此对他们来说它无法证明任何东西，而对其他人来说则标识了工作。将推理带过来；条目留在原地。

包文件和失败形式是使建议在此处可操作的东西。匿名化规则剥离的一切都是仅来自其来源仓库的单次可读细节。

保持简短。这是一个建议草案，而不是一个工作建议——/improve-pipeline 是用于开发建议的，而此阶段稍后的 /improve-pipeline 推荐仍然成立：推荐它，不要调用它。在条目中引用问题编号。 未引用的提交再次成为散文：条目命名 #N，否则第五个名称未被使用。

兔子洞审查。

…

[为翻译截断]