discovery

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

/discovery — Full Discovery Phase Orchestrator

/discovery — 全发现阶段编排器

Quick Ref: Brainstorm → search history → research → plan → pre-mortem. Produces an epic-id and execution-packet ready for
/crank
.

YOU MUST EXECUTE THIS WORKFLOW. Do not just describe it.

快速参考： 头脑风暴 → 历史搜索 → 调研 → 规划 → 事前分析。生成可用于
/crank
的epic-id和执行数据包。

你必须执行此工作流，不能仅描述它。

Quick Start

快速开始

bash

/discovery "add user authentication"              # full discovery
/discovery --interactive "refactor payment module" # human gates in research + plan
/discovery --skip-brainstorm "fix login bug"       # skip brainstorm for specific goals
/discovery --complexity=full "migrate to v2 API"   # force full council ceremony

bash

/discovery "add user authentication"              # 完整发现流程
/discovery --interactive "refactor payment module" # 在调研和规划阶段加入人工关卡
/discovery --skip-brainstorm "fix login bug"       # 针对特定目标跳过头脑风暴
/discovery --complexity=full "migrate to v2 API"   # 强制启用完整评审流程

Architecture

架构

/discovery <goal> [--interactive] [--complexity=<fast|standard|full>] [--skip-brainstorm]
  │
  ├── Step 1: Brainstorm (optional)
  │   └── /brainstorm <goal> — clarify WHAT before HOW
  │
  ├── Step 2: Search History
  │   └── ao search "<goal keywords>" — surface prior learnings
  │
  ├── Step 3: Research
  │   └── /research <goal> — deep codebase exploration
  │
  ├── Step 4: Plan
  │   └── /plan <goal> — decompose into epic + issues
  │
  └── Step 5: Pre-mortem (gate)
      └── /pre-mortem — council validates the plan
          PASS/WARN → output epic-id + execution-packet
          FAIL → re-plan with findings, max 3 attempts

/discovery <goal> [--interactive] [--complexity=<fast|standard|full>] [--skip-brainstorm]
  │
  ├── 步骤1：头脑风暴（可选）
  │   └── /brainstorm <goal> — 先明确目标再考虑实现方式
  │
  ├── 步骤2：历史搜索
  │   └── ao search "<goal keywords>" — 挖掘过往经验
  │
  ├── 步骤3：调研
  │   └── /research <goal> — 深度探索代码库
  │
  ├── 步骤4：规划
  │   └── /plan <goal> — 分解为epic和任务
  │
  └── 步骤5：事前分析（关卡）
      └── /pre-mortem — 评审团验证规划
          通过/警告 → 输出epic-id + 执行数据包
          失败 → 结合发现重新规划，最多3次尝试

Execution Steps

执行步骤

Step 0: Setup

步骤0：设置

bash

mkdir -p .agents/rpi

Initialize state:

discovery_state = {
  goal: "<goal string>",
  interactive: <true if --interactive>,
  complexity: <fast|standard|full or null for auto-detect>,
  skip_brainstorm: <true if --skip-brainstorm or goal is >50 chars and specific>,
  epic_id: null,
  attempt: 1,
  verdict: null
}

CLI dependency detection:

bash

undefined

bash

mkdir -p .agents/rpi

初始化状态：

discovery_state = {
  goal: "<goal string>",
  interactive: <true if --interactive>,
  complexity: <fast|standard|full or null for auto-detect>,
  skip_brainstorm: <true if --skip-brainstorm or goal is >50 chars and specific>,
  epic_id: null,
  attempt: 1,
  verdict: null
}

CLI依赖检测：

bash

undefined

Tracking mode

跟踪模式

if command -v bd &>/dev/null; then TRACKING_MODE="beads"; else TRACKING_MODE="tasklist"; fi

Knowledge flywheel

知识飞轮

if command -v ao &>/dev/null; then AO_AVAILABLE=true; else AO_AVAILABLE=false; fi

undefined

if command -v ao &>/dev/null; then AO_AVAILABLE=true; else AO_AVAILABLE=false; fi

undefined

Step 1: Brainstorm (optional)

步骤1：头脑风暴（可选）

Skip if:

--skip-brainstorm

flag, OR goal is >50 chars and contains no vague keywords (improve, better, something, somehow, maybe), OR a brainstorm artifact already exists for this goal in

.agents/brainstorm/

Otherwise: Invoke

/brainstorm

to clarify WHAT before HOW:

Skill(skill="brainstorm", args="<goal>")

If brainstorm produces a refined goal, use the refined goal for subsequent steps.

跳过条件： 使用

--skip-brainstorm

参数，或目标长度超过50字符且无模糊关键词（如improve、better、something、somehow、maybe），或

.agents/brainstorm/

中已存在该目标的头脑风暴产物。

否则： 调用

/brainstorm

先明确目标再考虑实现方式：

Skill(skill="brainstorm", args="<goal>")

如果头脑风暴生成了优化后的目标，后续步骤将使用该优化目标。

Step 2: Search History

步骤2：历史搜索

Skip if:

ao

CLI is not available.

Otherwise: Search for prior session learnings relevant to the goal:

bash

ao search "<goal keywords>" 2>/dev/null || true
ao lookup --query "<goal keywords>" --limit 5 2>/dev/null || true

Summarize any relevant findings (prior attempts, related decisions, known constraints) and carry them forward as context for research.

Ranked packet requirement: Before leaving discovery, assemble a lightweight ranked packet for the current goal:

matching compiled planning rules / pre-mortem checks
matching active findings from
```
.agents/findings/*.md
```
matching unconsumed high-severity items from
```
.agents/rpi/next-work.jsonl
```

Rank by literal goal-text overlap first, then issue-type / work-shape overlap, then file-path or module overlap when known. Discovery does not need the final file list yet, but it MUST surface the best matching high-severity next-work items so planning can incorporate them instead of rediscovering them later.

跳过条件：

ao

CLI不可用。

否则： 搜索与目标相关的过往会话经验：

bash

ao search "<goal keywords>" 2>/dev/null || true
ao lookup --query "<goal keywords>" --limit 5 2>/dev/null || true

总结所有相关发现（过往尝试、相关决策、已知约束），并作为调研阶段的上下文。

排序数据包要求： 在完成发现阶段前，需为当前目标整理一个轻量级排序数据包，包含：

匹配已编译的规划规则/事前分析检查项
匹配
```
.agents/findings/*.md
```
中的有效发现
匹配
```
.agents/rpi/next-work.jsonl
```
中未处理的高优先级事项

排序规则：首先按目标文本字面匹配度排序，其次按任务类型/工作形态匹配度排序，已知文件路径或模块时按模块匹配度排序。发现阶段无需最终文件列表，但必须筛选出最匹配的高优先级待办事项，以便规划阶段直接纳入，避免后续重复发现。

Step 3: Research

步骤3：调研

Invoke

/research

for deep codebase exploration:

Skill(skill="research", args="<goal> [--auto]")

Pass

--auto

unless

--interactive

was specified. Research output lands in

.agents/research/

调用

/research

进行代码库深度探索：

Skill(skill="research", args="<goal> [--auto]")

除非指定

--interactive

，否则传递

--auto

参数。调研结果将保存至

.agents/research/

。

Step 3.1: Identify Applicable Test Levels

步骤3.1：确定适用的测试级别

After research completes, determine which test levels (L0–L3) the goal requires. Read the test pyramid standard (

test-pyramid.md

in the standards skill) for the full pyramid and selection guide.

Ask:

Does the change touch external APIs or I/O? → L0 + L1 + L2 minimum
Does it cross module boundaries? → Add L2
Does it affect a full subsystem workflow? → Add L3

Record the applicable levels in

discovery_state.test_levels

for downstream

/plan

consumption.

调研完成后，确定目标所需的测试级别（L0–L3）。请阅读标准文档中的测试金字塔规范（standards skill中的

test-pyramid.md

）获取完整金字塔模型和选择指南。

思考：

变更是否涉及外部API或I/O？→ 至少需要L0 + L1 + L2
是否跨模块边界？→ 增加L2
是否影响完整子系统工作流？→ 增加L3

将适用的测试级别记录到

discovery_state.test_levels

，供下游

/plan

使用。

Step 4: Plan

步骤4：规划

Invoke

/plan

to decompose into an epic with trackable issues:

Skill(skill="plan", args="<goal> [--auto]")

Pass

--auto

unless

--interactive

was specified. Plan output lands in

.agents/plans/

and creates issues via

bd

or TaskList.

After plan completes:

Extract epic ID:
```
bd list --type epic --status open
```
(beads) or identify from TaskList.
Store in
```
discovery_state.epic_id
```
.
Carry forward the ranked packet summary (applied findings, known risks, high-severity next-work matches) into the execution packet and phase summary.
Auto-detect complexity (if not overridden):
- Count issues:
```
bd children <epic-id> | wc -l
```
- Low: 1-2 issues →
```
fast
```
- Medium: 3-6 issues →
```
standard
```
- High: 7+ issues or 3+ waves →
```
full
```

调用

/plan

将目标分解为包含可跟踪任务的epic：

Skill(skill="plan", args="<goal> [--auto]")

除非指定

--interactive

，否则传递

--auto

参数。规划结果将保存至

.agents/plans/

，并通过

bd

或TaskList创建任务。

规划完成后：

提取epic ID：
```
bd list --type epic --status open
```
（beads模式）或从TaskList中识别。
保存至
```
discovery_state.epic_id
```
。
将排序数据包摘要（已应用的发现、已知风险、匹配的高优先级待办事项）纳入执行数据包和阶段总结。
自动检测复杂度（未指定时）：
- 统计任务数量：
```
bd children <epic-id> | wc -l
```
- 低复杂度：1-2个任务 →
```
fast
```
- 中复杂度：3-6个任务 →
```
standard
```
- 高复杂度：7个及以上任务或3个及以上阶段 →
```
full
```

Step 5: Pre-mortem (gate)

步骤5：事前分析（关卡）

Invoke

/pre-mortem

to validate the plan:

Skill(skill="pre-mortem", args="[--quick]")

Use

--quick

for fast/standard complexity. Use full council (no

--quick

) for full complexity or

--deep

override.

Gate logic (max 3 attempts):

PASS/WARN: Proceed. Store verdict in
```
discovery_state.verdict
```
.

FAIL: Retry loop:

Read pre-mortem report:

ls -t .agents/council/*pre-mortem*.md | head -1

Extract structured findings (description, fix, ref)

Log:

"Pre-mortem: FAIL (attempt N/3) -- retrying plan with feedback"

Re-invoke

/plan

with findings context:

Skill(skill="plan", args="<goal> --auto --context 'Pre-mortem FAIL: <findings>'")

Re-invoke
```
/pre-mortem
```

If still FAIL after 3 total attempts, stop:

"Pre-mortem failed 3 times. Last report: <path>. Manual intervention needed."

Output:

<promise>BLOCKED</promise>

调用

/pre-mortem

验证规划：

Skill(skill="pre-mortem", args="[--quick]")

快速/标准复杂度使用

--quick

参数，完整复杂度或

--deep

覆盖时使用完整评审流程（不添加

--quick

）。

关卡逻辑（最多3次尝试）：

通过/警告： 继续执行。将结果保存至
```
discovery_state.verdict
```
。

失败： 重试循环：

读取事前分析报告：

ls -t .agents/council/*pre-mortem*.md | head -1

提取结构化发现（描述、修复方案、参考）

记录日志：

"Pre-mortem: FAIL (attempt N/3) -- retrying plan with feedback"

结合发现上下文重新调用

/plan

：

Skill(skill="plan", args="<goal> --auto --context 'Pre-mortem FAIL: <findings>'")

重新调用
```
/pre-mortem
```

如果3次尝试均失败，停止执行：

"Pre-mortem failed 3 times. Last report: <path>. Manual intervention needed."

输出：

<promise>BLOCKED</promise>

Step 6: Output

步骤6：输出

After successful gate (PASS/WARN): write execution packet and phase summary (read

references/output-templates.md

for formats), record ratchet, output

<promise>DONE</promise>

, and report epic-id with suggested next step:

/crank <epic-id>

. Include

test_levels

from Step 3.1 in the execution packet for

/crank

consumption.

关卡通过后（通过/警告）：编写执行数据包和阶段总结（格式参考

references/output-templates.md

），记录进度，输出

<promise>DONE</promise>

，并返回epic-id及建议下一步操作：

/crank <epic-id>

。执行数据包中需包含步骤3.1的

test_levels

，供

/crank

使用。

Flags

参数

Flag	Default	Description
`--interactive`	off	Human gates in research and plan
`--skip-brainstorm`	auto	Skip brainstorm step
`--complexity=<level>`	auto	Force complexity level (fast/standard/full)
`--no-budget`	off	Disable phase time budgets

参数	默认值	描述
`--interactive`	关闭	在调研和规划阶段加入人工关卡
`--skip-brainstorm`	自动	跳过头脑风暴步骤
`--complexity=<level>`	自动	强制指定复杂度级别（fast/standard/full）
`--no-budget`	关闭	禁用阶段时间预算

Completion Markers

完成标记

<promise>DONE</promise>      # Discovery complete, epic-id + execution-packet ready
<promise>BLOCKED</promise>   # Pre-mortem failed 3x, manual intervention needed

<promise>DONE</promise>      # 发现阶段完成，epic-id + 执行数据包已就绪
<promise>BLOCKED</promise>   # 事前分析3次失败，需人工干预

Examples

示例

bash

/discovery "add user authentication"              # full discovery
/discovery --interactive "refactor payment module" # human gates
/discovery --skip-brainstorm "fix login bug"       # skip brainstorm

bash

/discovery "add user authentication"              # 完整发现流程
/discovery --interactive "refactor payment module" # 启用人工关卡
/discovery --skip-brainstorm "fix login bug"       # 跳过头脑风暴

Troubleshooting

故障排除

Read

references/troubleshooting.md

for common problems and solutions.

请阅读

references/troubleshooting.md

获取常见问题及解决方案。

Reference Documents

参考文档

references/complexity-auto-detect.md — precedence contract for keyword vs issue-count classification
references/idempotency-and-resume.md — re-run safety and resume behavior
references/phase-budgets.md — time budgets per complexity level
references/troubleshooting.md — common problems and solutions
references/output-templates.md — execution packet and phase summary formats

See also: brainstorm, research, plan, pre-mortem, crank, rpi

references/complexity-auto-detect.md — 关键词与任务数量分类的优先级约定
references/idempotency-and-resume.md — 重入安全与恢复机制
references/phase-budgets.md — 不同复杂度级别的时间预算
references/troubleshooting.md — 常见问题及解决方案
references/output-templates.md — 执行数据包与阶段总结格式

另请参阅： brainstorm, research, plan, pre-mortem, crank, rpi