opportunity-scan

机会扫描 — 根据实际发生的情况找出需要改变的内容

读取 Agent 自身的能力以及你选择的一个目标，并建议将每项发现转化为哪种原语。与 Agent 无关（Claude Code、Codex、PI，……）。它会将发现映射到完整的原语类型（规则 · 技能 · 钩子 · 子 Agent · MCP · 自动化/工作流），并且适用于任何 Agent，因为它会先了解该 Agent 的能力。

两个目标，一项技能——这就是全部设计：

• 一次运行 → 响应式循环。 你运行的某个循环刚刚出了问题。将扫描指向该次运行留下的产物，并询问*“AI 层中有什么可以避免这种情况？”*你要修复的是系统，而不是代码。
• 一段时间的日志 → 主动扫描。 没有任何故障。将扫描指向数周的会话，并询问*“我一直在手动做哪些本该编码固化的事？”*

同一项技能，同一种输出格式——你只是改变了它读取的内容。

这是一种发现工具——用于判断要改变什么——而不是质量评估工具（用于判断已构建的东西是否良好）。请将两者分开。

输入 — 先提供必需项，再提供可选项

将 $ARGUMENTS 作为自然语言文本读取，而不是按位置分配的槽位。只有输入 1 是必需的。输入 2 是自由格式的，其中可能包含空格，因此绝不要按空白字符拆分参数，也不要按位置绑定——不加引号输入的引导内容仍然是一个整体。如果缺少信息，请在一条消息中一次性询问，不要逐个提问。

1. 要扫描的内容（必需）——必须且只能是以下一项：
   • 一次运行（响应式）——某个循环留下的产物：计划、实施报告、RCA、PR 正文、审查结果、提交记录/差异。尽可能附上该次运行的会话日志，并指出其位置。这些内容已经限定在该次运行的范围内，因此无需搜索会话。
   • 一段时间的日志（主动式）——Agent 保存会话日志的位置，以及要回溯多长时间。例如：Claude Code → ~/.claude/projects/ + ~/.claude/history.jsonl；Codex → ~/.codex/sessions/；PI → 你的扩展日志目录。默认时间范围：过去 2 周。

这个选择决定扫描是响应式还是主动式。其他一切都不变。 2. 你的引导内容（可选——只询问一次，并接受“没有特别要求”）——一个输入，具体含义取决于目标：

• 扫描一次运行：你注意到的症状，用你自己的话描述——Agent 哪里做错了、你不得不纠正什么、什么让你感到恼火。你亲历了整个过程；你能直接说出的内容，不必让扫描再从产物中推导。*（这是单句外层循环中的“你刚刚做了 X”；工具化版本也接受同样的 X。）*只描述观察到的情况；找出发生原因是扫描的工作，不是你的。
• 扫描日志：你关心的主题——你想停止手动完成的工作类型、你反复坚持的质量标准，或循环中总让你付出代价的环节。如果没有引导内容，扫描只会按频率排序，而频率排序并不等同于按你在意的程度排序。

无论哪种情况：引导内容由你提供，证据由目标提供。 3. Agent 自身的能力文档（可选——通常应由你自行查找）——让扫描了解你的 Agent 能够扩展成什么样（其实际扩展点）。**先自行查找，不要先询问。**判断当前使用的是哪种 Agent，并查找其自身的扩展文档（对于 Claude Code，即 code.claude.com/docs）。只有在确实无法确定，或用户希望你查找特定位置时才询问。绝不要假设扩展点有固定集合：应从你实际找到的文档中读取。

步骤 — 按原样执行；这是容易出错的部分（元提示）

1. 了解自身能力。 确定你当前运行的是哪个 Agent，并阅读其能力文档（输入 3，通常由你自行解析）。简要列出当前 Agent 的扩展点（规则、技能、钩子、子 Agent、MCP/工具、自动化/工作流，或文档所述的其他内容）。以文档为准——不要假定扩展点类型是固定的。

2. 阅读目标 — 根据输入 1 的内容选择分支：

   • **一次运行：**完整阅读相关材料——它们篇幅不长，细节才是重点。如果输入 2 提到了某个症状，从那里开始：在材料中找到该症状，并根据实际发生的情况进行核实，而不是从头重新推导用户已经告诉你的内容。然后还原本次运行的其余过程：用户提出了什么要求、Agent 做了什么、哪里出了问题、哪里需要纠正、它做了哪些假设、跳过了哪些内容——提到的症状只是切入点，不是视野局限。最后阅读差异，作为证据，而不是分析对象。
   • **一段日志窗口：**提取你实际做过的事情——反复执行的命令、重复的多步操作、重复的指示/纠正、调用过的工具、遇到的阻碍/重试。**汇总，而非全盘读取：**日志可能很庞大——优先查看提示词/命令历史文件，而不是原始记录，并使用 Shell 工具（jq/grep/sort | uniq -c）进行精简，只让频次和代表性样本进入上下文，切勿导入整份日志文件。

   无论哪种情况：如果无法找到或解析目标，请询问用户，不要凭空编造。

3. 找出要改进之处 — 根据目标不同，问题也不同：

   • 一次运行（响应式）：针对每个出错或需要纠正的地方，询问“AI 层要做出什么改变才能避免这个问题？”指出能够发现问题的最小持久性改动——例如规则中的一行、技能中新增的一步、一个钩子，或更严格的工具权限范围；具体到今天就能实施。**修复系统，而非代码：**不要提出代码修复方案，而要提出能够让代码修复变得多余或自动完成的改动。⚠️ 并非每次失败都意味着系统存在缺陷——如果某个问题无法通过任何持久性改动来预防，就直说，不要为一次性事件编造规则。坦诚地说一句“这里无需改动”，胜过五条推测性规则。
   • **日志（主动式）：针对每种重复模式，询问“应该把它转化成什么？”**大致按（出现频率 × 可减少的重复输入量）排序。

   针对两类目标：从步骤 1 的列表中选择最合适的基础机制，并说明原因。如果提供了输入 2，要给予相应权重——对于一次运行，报告应优先说明如何预防所提到症状（如果证据表明实际问题另有其事，也要直说）；对于日志，即使用户关心的事项并非最常见，也要将其列出；若某个高频模式不值得编码，也要直说。每项改动都应采用现有材料的惯用风格：先浏览项目中现有的几份规则/技能/Agent，再据此调整建议的形式，让建议看起来像用户实际会采用的内容。映射示例：

   • 反复重申的规则 → 规则（CLAUDE.md / AGENTS.md）
   • 重复的多步工作流 → 技能
   • 必须始终遵守或绝不可违反、但你一直靠手动执行的要求 → 钩子
   • 反复进行的专门委派 → 子 Agent
   • 经常执行的完整端到端交接 → 自动化（之后可转为 Archon 工作流）

4. 撰写报告，将其制作为一个独立的 HTML 文件（见下方约定），然后告知用户文件位置。

报告规范——规定如何呈现，绝不规定包含什么

让分析决定报告内容。 有哪些章节、各章节写什么、每个章节深入到什么程度、列出多少个机会、哪些引述或数字值得摘录——这些都应取决于你实际发现的内容，而不是这项技能。不要把报告限制在固定的章节集合中，不要预设发现，不要规定报告该得出什么结论。如果数据丰富，报告就应内容丰富；如果某项发现值得单独深入分析，就为它单设一节；如果出现意外发现，就把它呈现出来。

只规定呈现方式：

• 一个自包含的 .html 文件（内嵌 CSS），可在任何浏览器中打开。
• 视觉简洁、便于浏览且留有充足空间——让发现充分呈现；根据实际发现，选用最合适的布局、章节、真实引述、统计数据或可视化内容。

规则：这项技能规定的是如何呈现在页面上，绝不规定页面上放什么。

保持轻量

严格只执行以下四个步骤，并清楚呈现。不要添加评分框架、配置或不必要的额外流程。如果某个步骤无法完成（找不到文档或目标），就停止并询问——绝不要捏造分析结果。 每次运行只扫描一个目标。 如果有人既想了解反应式视角，也想了解主动式视角，就分两次运行并生成两份报告——把“这一轮中出了什么问题”和“一个月来我反复做了什么”混在一起，会让报告无法清楚回答任何一个问题。