Back to Details

opportunity-scan

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Opportunity Scan — find what to change, from what actually happened

机会扫描——从实际发生的情况中找出需要调整的内容

Reads your agent's own capabilities plus one target you choose, and recommends which primitive each finding should become. Agent-agnostic (Claude Code, Codex, PI, …). It maps what it finds to the full primitive palette (rules · skill · hook · subagent · MCP · automation/workflow), and it works for any agent because it learns that agent's capabilities first.
Two targets, one skill — this is the whole design:
  • A run → the REACTIVE loop. Something just went sideways in a loop you ran. Point the scan at that run's artifacts and ask "what in the AI layer would have prevented this?" You fix the system, not the code.
  • A window of logs → the PROACTIVE scan. Nothing is broken. Point it at weeks of sessions and ask "what do I keep doing by hand that should be encoded?"
Same skill, same output shape — you're just changing what it reads.
This is a discovery tool — what to change — NOT a quality eval (whether a built thing is good). Keep the two separate.
读取你的Agent自身能力，加上你选择的一个目标，并为每个发现推荐应转化为哪种原语。该工具与Agent无关（支持Claude Code、Codex、PI等）。它会将发现的内容映射到完整的原语库（rules·skill·hook·subagent·MCP·automation/workflow），并且适用于任意Agent，因为它会先学习该Agent的能力。
两种目标，同一工具——这就是完整设计：
  • 单次运行 → 响应式循环：你刚运行的一次循环出现了问题。将扫描工具指向该次运行的产物，提问“AI层中哪些调整本可避免这个问题？”。你要修复的是系统，而非代码。
  • 一段日志 → 前瞻性扫描：没有出现故障。将工具指向数周的会话记录，提问“我一直在手动完成的哪些工作应该被固化？”
同一工具，输出格式一致——只是读取的目标不同。
这是一款发现类工具——用于找出需要调整的内容，而非质量评估工具（评估已构建内容的优劣）。请将两者区分开。

Inputs — required first, then optional

输入——先必填，后可选

Read 
$ARGUMENTS
as prose, not as positional slots. Only input 1 is required. Input 2 is free-form and will contain spaces, so never split arguments on whitespace and never bind them by position — a steer typed without quotes is still one steer. If something is missing, ask for it once, in a single message, not one question at a time.
  1. What to scan (required) — exactly one of:
    • A RUN (reactive) — the artifacts one loop left behind: the plan, the implementation report, an RCA, the PR body, the review output, the commits/diff. Add that run's session log too if you can point at it. These are already scoped to the run, so there's no session-hunting to do.
    • A WINDOW OF LOGS (proactive) — where your agent keeps session logs, plus how far back. Examples: Claude Code → 
      ~/.claude/projects/
      + 
      ~/.claude/history.jsonl
      ; Codex → 
      ~/.codex/sessions/
      ; PI → your extension's log dir. Default window: the last 2 weeks.
    This choice is what makes the scan reactive or proactive. Nothing else changes.
  2. Your steer (optional — ask once, accept "nothing specific") — one input, whose meaning follows the target:
    • Scanning a RUN: the symptom you noticed, in your words — what the agent got wrong, what you had to correct, what annoyed you. You were there; don't make the scan re-derive from the artifacts what you can just say. (This is the "you just did X" of the one-sentence outer loop — the tooled version accepts the same X.) Keep it to the observation; working out why it happened is the scan's job, not yours.
    • Scanning LOGS: the theme you care about — the kind of work you want to stop doing by hand, a quality bar you keep enforcing, a part of the loop that keeps costing you. Without it the scan just ranks by frequency, which is not the same as ranking by what matters to you.
    Either way: you supply the steer, the target supplies the evidence.
  3. The agent's own capability docs (optional — normally resolve this yourself) — so the scan knows what your agent can become (its real extension points). Work it out; do not ask first. Identify which agent you are running as and find its own extensibility docs (for Claude Code that is 
    code.claude.com/docs
    ). Only ask if you genuinely cannot determine it, or if the user wants you pointed somewhere specific. Never assume a fixed set of extension points: read them from whatever docs you actually find.
将
$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
    ）。仅在确实无法确定，或用户希望指向特定位置时才询问。切勿假设固定的扩展点集合：从实际找到的文档中读取。

Steps — keep them literal; this is the fragile part (meta-prompting)

步骤——严格按字面执行；这是容易出错的部分（元提示）

  1. Learn your own capabilities. Determine which agent you are running as and read its capability docs (input 3, which you normally resolve yourself). Write a short internal list of this agent's extension points (rules, skill, hook, subagent, MCP/tool, automation/workflow, whatever the docs describe). Use what the docs say — do not assume a fixed set.
  2. Read the target — branch on what input 1 was:
    • A RUN: read the artifacts in full — they're small, and the detail is the point. If input 2 named a symptom, start there: find it in the artifacts and verify it against what actually happened, rather than re-deriving from scratch what the user already told you. Then reconstruct the rest of the run: what was asked, what the agent did, where it went wrong, where it had to be corrected, what it assumed, what it skipped — the named symptom is the entry point, not a blinder. Read the diff last, as evidence rather than as the subject.
    • A WINDOW OF LOGS: pull out what you actually did — recurring commands, repeated multi-step sequences, repeated instructions/corrections, tools reached for, friction/retries. Aggregate, don't ingest: logs can be huge — prefer the prompt/command-history file over raw transcripts, and reduce with shell tools (
      jq
      /
      grep
      /
      sort | uniq -c
      ) so only frequencies and representative samples enter your context, never whole log files.
    Either way: if you can't locate or parse the target, ask the user rather than invent.
  3. Find what to change — the question differs by target:
    • RUN (reactive): for each thing that went wrong or needed correcting, ask "what in the AI layer would have prevented this?" Name the smallest durable change that would have caught it — a line in a rule, a step added to a skill, a hook, a tighter tool scope — specific enough to apply today. Fix the system, not the code: do not propose the code fix, propose the thing that would have made the code fix unnecessary or automatic. ⚠️ Not every failure is a system gap — if something went wrong that no durable change would have prevented, say so plainly instead of inventing a rule for a one-off. One honest "nothing to change here" is worth more than five speculative rules.
    • LOGS (proactive): for each recurring pattern, ask "what should this become?" Rank by roughly (how often it occurs × how much encoding it would save).
    Both targets: pick the best-fit primitive (from step 1's list) and say why. If input 2 was given, weight it — on a run, the named symptom's prevention leads the report (and if the evidence says the symptom was actually something else, say so plainly); on logs, surface what the user said they care about even when it isn't the most frequent pattern, and say plainly when a high-frequency pattern is not worth encoding. And propose each change in the house style of the artifacts that already exist: skim a couple of the project's current rules/skills/agents first and shape the recommendation to look like them, so what it suggests is something the user would actually build. Examples of the mapping:
    • a rule you keep restating → rules (CLAUDE.md / AGENTS.md)
    • a repeated multi-step workflow → a skill
    • a must-never / must-always you keep enforcing by hand → a hook
    • a specialized recurring delegation → a subagent
    • a clean end-to-end hand-off you do often → an automation (later: an Archon workflow)
  4. Write the report as a single self-contained HTML file (see the contract below), then tell the user where it is.
  1. 了解自身能力：确定你正在使用的Agent类型，并读取其能力文档（输入3，通常自行获取）。编写一份简短的内部列表，记录该Agent的扩展点（rules、skill、hook、subagent、MCP/工具、automation/workflow，或文档中描述的任何内容）。以文档内容为准——切勿假设固定集合。
  2. 读取目标——根据输入1的类型分支处理：
    • 单次运行：完整读取产物——产物内容不多，细节才是关键。若输入2指定了问题现象，从该现象入手：在产物中找到该现象，并与实际发生的情况进行验证，而非从头重新推导用户已告知的内容。然后重构整个运行过程：需求是什么，Agent做了什么，哪里出错了，哪里需要纠正，Agent做了哪些假设，跳过了哪些步骤——指定的现象是切入点，而非限制。最后读取差异内容，将其作为证据而非分析对象。
    • 一段日志：提取你实际执行的操作——重复的命令、重复的多步骤序列、重复的指令/纠正、使用的工具、摩擦/重试情况。汇总而非全盘读取：日志可能非常庞大——优先使用提示/命令历史文件，而非原始转录本，并使用Shell工具（
      jq
      /
      grep
      /
      sort | uniq -c
      ）进行精简，仅将频率和代表性样本纳入上下文，切勿读取完整日志文件。
    无论哪种情况：若无法定位或解析目标，询问用户而非自行编造。
  3. 找出需要调整的内容——问题随目标不同而变化：
    • 单次运行（响应式）：针对每个出错或需要纠正的内容，提问“AI层中哪些调整本可避免这个问题？”。指出最小的持久化调整——规则中的一行内容、skill中添加的一个步骤、hook、更严格的工具范围——具体到可立即实施。修复系统，而非代码：不要提出代码修复方案，而是提出可使代码修复变得不必要或自动化的改进点。⚠️ 并非所有故障都是系统缺口——若某次故障无法通过持久化调整避免，请明确说明，而非为偶发情况编造规则。一句诚实的“此处无需调整”胜过五条推测性规则。
    • 日志（前瞻性）：针对每个重复模式，提问“这应该转化为哪种原语？”。大致按（发生频率 × 固化后节省的工作量）排序。
    两种目标通用规则：选择最匹配的原语（来自步骤1的列表）并说明原因。若提供了输入2，优先考虑该引导语——在单次运行扫描中，指定现象的预防措施应放在报告首位（若证据显示实际现象与用户描述不同，请明确说明）；在日志扫描中，即使并非最频繁的模式，也要优先呈现用户关注的内容，若高频模式不值得固化，也请明确说明。并且按照现有产物的风格提出每个调整建议：先浏览几个项目当前的rules/skills/agents，使建议风格与之匹配，确保用户实际会采纳这些建议。映射示例：
    • 你一直在重复说明的规则 → rules（CLAUDE.md / AGENTS.md）
    • 重复的多步骤工作流 → skill
    • 你一直在手动执行的“严禁/必须”规则 → hook
    • 重复的专项委托任务 → subagent
    • 你经常执行的清晰端到端交接 → automation（后续：Archon工作流）
  4. 生成报告：将报告写为单个自包含HTML文件（见下方约定），然后告知用户报告位置。

Report contract — prescribe HOW to render, never WHAT to include

报告约定——规定渲染方式，而非内容

Let the analysis drive the report. Which sections exist, what goes in them, how deep each goes, how many opportunities, which quotes or numbers are worth pulling out — all of that comes from what you actually found, NOT from this skill. Do not box the report into a fixed set of sections, do not seed findings, do not tell it what to conclude. If the data is rich, the report is rich; if a single finding deserves its own deep section, give it one; if something surprising turns up, surface it.
Only the rendering is prescribed:
  • One self-contained 
    .html
     file (inline CSS), opens in any browser.
  • Visually clean, scannable, and generous — let the findings breathe; use whatever layout, sections, real quotes, stats, or visuals best fit what was actually found.
The rule: this skill governs how to put it on the page, never what goes on the page.
让分析结果主导报告内容。报告包含哪些章节、各章节内容、深度、机会数量、值得引用的语句或数据——所有这些都取决于实际发现的内容，而非本工具的要求。切勿将报告限制在固定章节中，切勿预设发现内容，切勿指定结论。若数据丰富，报告则内容详实；若单个发现值得单独深入分析，则为其设立独立章节；若出现意外发现，则重点呈现。
仅渲染方式为固定要求：
  • 单个**自包含的
    .html
    **文件（内联CSS），可在任意浏览器中打开。
  • 视觉简洁、易于浏览、布局宽松——让发现内容清晰呈现；使用最适合实际发现内容的布局、章节、真实引用、统计数据或视觉元素。
规则：本工具仅管控页面呈现方式，绝不干预页面内容。

Keep it light

保持简洁

Do exactly these four steps, clearly. Don't add scoring frameworks, config, or extra passes it doesn't need. If a step can't complete (docs or the target not found), stop and ask — never fabricate the analysis. Scan one target per run. If someone wants both the reactive and the proactive view, that's two runs and two reports — mixing "what broke in this loop" with "what I keep repeating across a month" produces a report that answers neither question well.
严格执行这四个步骤，清晰明了。无需添加评分框架、配置或不必要的额外步骤。若某一步无法完成（未找到文档或目标），请停止并询问——切勿编造分析内容。每次运行仅扫描一个目标。若有人同时需要响应式和前瞻性视图，需分两次运行生成两份报告——将“本次循环中出现的故障”与“一个月内重复的操作”混合，会导致报告无法很好地回答任何一个问题。