| name | automation-optimizer |
| description | 分析 Issue Flow 某个阶段为何需要多轮人工介入，依据完整 TaskEvent 找出 Agent 首次未完成的真实原因，选择可长期消除原因的改进方式，并生成结构化 Optimization Plan JSON。适用于 triage、plan、build 或 review 阶段 Turns 大于 1 后发起的自动化优化分析。 |
自动化优化分析
分析 Agent 为什么没有在首次 Task 中完成阶段目标，并设计能够减少同类人工介入的改进。人工评论描述的是这次需要纠正什么，只能作为线索，不能直接改写成根因或长期规则。
从优化 Issue 正文读取来源 Issue、待优化阶段及其 Turns。先读取 Optimization Plan 产物协议。本任务只生成分析产物，不实施改进方案。
获取执行上下文
执行一次脚本，获取来源 Issue 整个生命周期的 Task：
node .agentrix/plugins/issue-flow/skills/automation-optimizer/scripts/task-context.cjs \
--issue <来源 Issue 编号>
脚本输出临时索引文件以及 triage、plan、build、review 阶段文件。每个阶段文件包含该阶段全部 Task 和全部 events。不要筛选事件类型，不要把临时文件放入仓库或提交到 Git。
先读索引和优化 Issue 指定的阶段。只有当前阶段不足以解释问题来源或传播过程时，才读取相关上下游阶段。某阶段没有 Task、事件不完整或来源 Issue 无法确定时，不得猜测根因，应在 Plan 中记录缺失证据及其影响。
分析原则
- 分析“为什么会发生”，不要只总结“哪里做错了”。
- “考虑不完整”“缺少验证”“没有覆盖边界”“理解不足”只是直接原因，不能作为最终根因。
- 不得把后续人工评论改写成祈使句后称为根因或规范。
- 不要用后续评论倒推首次执行时不可能知道的要求。
- 每个原因都必须由
taskId + sequence、仓库代码、项目文档或测试事实支撑。
- Task ID、sequence 和事件流水只用于分析取证，不写入最终产物的目标与原因。
- 不强制为每个问题生成规范；先确定原因，再选择最合适的改进去向。
- 优先消除诱发错误的结构，而不是要求 Agent 下次“更仔细”。
分析步骤
1. 定义首次完成标准
根据首次 Task Message、来源 Issue、当时仓库内容和已有项目约定，确定该阶段首次 Task 应完成的产物、操作、验证和结束状态。
2. 还原首次判断
按 sequence 还原目标阶段的初始输入、Agent 的理解和操作、工具结果、首次交付、人工纠正及最终结果。对每次人工介入回答：
- 首次结果与最终正确结果有什么差异？
- Agent 在首次交付前作出了什么错误判断或遗漏了什么决策？
- Agent 当时看到了哪些证据，为什么会认为原判断足够？
- 正确信息当时是否存在于 Issue、代码、测试、项目说明或项目文档中？
- 如果信息存在，Agent 是否搜索、读取并正确应用；如果没有，为什么没有找到或为什么选择猜测？
- 如果问题可机械验证，现有测试或检查为什么没有暴露它？
- 哪个最早的机制能够稳定消除该原因，而不只是提醒以后注意？
- 采用该改进后，这次人工介入是否自然不再需要？
3. 检查项目知识与文档
只要问题涉及业务背景、项目约定、已有能力或历史决策，必须检查仓库中的 README、文档目录、ADR、架构说明及相关代码注释，并核对 TaskEvent 中 Agent 是否读取过它们。区分：
- 信息不存在；
- 信息存在但不完整、错误、过期或互相冲突；
- 信息正确但难以发现；
- Agent 已读取但理解或应用错误；
- Agent 没找到答案后未经确认直接猜测。
不要在已有文档可以补全时重复写项目规范，也不要用项目规范复制业务文档。
4. 按需进行跨阶段分析
如果当前阶段使用了上游产物、人工纠正指向上游遗漏，或多个待优化阶段可能属于同一因果链，再读取相关阶段。分别保留各阶段证据，并确定问题最早产生、传播和暴露的位置。
如果前一阶段已经产生了正确决策，但后续 Task 实际没有收到、收到错误版本或关联到错误 Task，判定为 Issue Flow 上下文传递 Bug，向开发者反馈；不得用项目规范掩盖。若上下文已经正确注入但 Agent 没有使用，再继续分析其执行、提示或信息发现原因。
选择改进去向
根据证据选择一项或多项改进，不得预设所有问题都修改 .issue-flow/instructions.md。
项目内改进
- 需求表达或业务决策缺失：改进 Issue 模板、需求说明或决策记录；不能从事实唯一推导的选择仍由人决定。
- 业务知识缺失：补充项目业务文档、术语、状态规则或历史决策。
- 已有文档不完整、错误或难发现：优先修正文档，并改善索引、命名或权威来源说明。
- 可泛化的项目执行方法缺失：修改
.issue-flow/instructions.md，写适用条件、分析方法和完成证据，不写当前任务专属检查清单。
- 稳定行为缺少确定性验证：补充或修正单元测试、集成测试、类型检查、checker 或 validation。
- 代码结构容易诱发错误：重构重复判断、隐式副作用、分散复制或多重权威来源，从结构上消除误用。
- 项目工具能力不足：改进项目内脚本、CLI 或辅助工具，使必要信息可获取、操作可执行、结果可验证。新增可供 Agent 使用的工具时，同时在
.issue-flow/instructions.md 中声明其适用场景、调用入口、必要输入、输出和使用边界，确保后续任务能够发现并正确使用；不要在项目说明中复制工具实现细节。
项目级执行规范统一写入 .issue-flow/instructions.md。除该文件外，不得生成修改 .issue-flow/ 下任何文件的方案。若根因属于 .issue-flow 体系内的流程、Skill、模板或脚本本身，生成 Issue Flow 开发者反馈，不作为当前项目改进方案。
项目开发者建议
如果改进需要当前项目维护者补齐仓库外或人工管理的前置能力，而 Agent 无法在本次优化中安全实施，例如构建环境、工具链、凭据、组织级基础设施或项目级运行配置，生成 kind: project-developer-feedback 的 Proposal：
- 明确当前项目开发者需要完成什么，以及完成后 Agent 如何发现和使用该能力；
- 不生成
issue，页面只展示建议内容和验证方式；
- 不提供复制、创建 Issue 或忽略操作，也不阻塞优化流程终态。
只要改动能够由 Agent 在当前仓库中实施，就仍使用 project-change，不得用项目开发者建议逃避可执行改进。
Issue Flow 开发者反馈
Issue Flow 未传递阶段上下文、关联错误 Task、注入错误版本，或者 .issue-flow 体系内的流程、Skill、模板、脚本等存在缺陷时，形成 Issue Flow 开发者反馈。至少记录：
- 预期行为与实际行为；
- 相关阶段、Task ID 和事件证据；
- 缺失或错误的上下文；
- 对首次完成的影响；
- 可复现条件。
不得把平台缺陷改写成项目长期规则，也不得声称项目改动已经修复底层问题。
Issue Flow 开发者 Bug 反馈必须生成 kind: issue-flow-feedback 的 Proposal，Issue 草稿使用 type::bug 与 flow::triage。
能够通过当前项目的仓库配置、构建入口、运行环境声明或项目维护动作解决的问题，不属于 Issue Flow 开发者反馈；应生成 project-change 或 project-developer-feedback。只有问题位于 .issue-flow 体系内的流程、Skill、模板、脚本等公共能力时，才反馈给 Issue Flow 开发者。
不形成长期改动
- 偶发网络、权限、服务或运行环境失败：记录证据；只有存在稳定恢复模式时才设计重试或可观察性改进。
- 无法自动消除的真实业务选择：说明为什么必须保留人工决策。
- 当前 Issue 的一次性偏好：记录为本次需求，不泛化。
泛化项目规范
只有根因属于可重复出现的项目执行方法缺口时，才写入 .issue-flow/instructions.md。规范应描述一类任务的处理方法，而不是复制本次验收项：
- 写清适用条件；
- 写清分析或执行方法；
- 写清可观察的完成证据；
- 删除本次类名、接口名、字段名、状态码和具体用例后，仍然清晰、可执行；
- 优先修改已有规范，避免重复或冲突。
如果删除任务专属名词后规则失去意义，它仍是本次修复准则，不是可沉淀规范。
Optimization Plan
产物只包含 target 与 proposals。target.summary 用一句话简述当前问题；target.cause 用 1–3 条短句概括根本原因，不写取证过程。Agent 可在仓库内执行的改动使用 project-change；需要当前项目维护者补齐外部能力时使用 project-developer-feedback；.issue-flow 体系内的公共能力缺陷使用 issue-flow-feedback。只有 project-developer-feedback 不携带 Issue 合同。多个阶段属于同一因果链时可以合并根因，但不同落点仍拆成独立 Proposal。
Proposal 只保留具体方案和验证方式。证据用于得出结论，不在产物中堆叠执行流水账。
硬性约束
- 不得只根据 Turns 数量推断根因。
- 不得忽略非消息类型的 TaskEvent。
- 不得在没有事件证据时补写执行过程。
- 不得把完整会话、敏感数据或临时上下文文件提交到仓库。
- 不得强制把所有问题转换成
.issue-flow/instructions.md。
- 不得用项目规则掩盖 Issue Flow 上下文传递或平台能力 Bug。
- 不得在本分析任务中实施优化改动。
