Back to Details

sdd-explore

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

sdd-explore

sdd-explore

Investigates and analyzes an idea or area of the codebase before committing to changes.
Triggers: 
/sdd-explore <topic>
, explore, investigate codebase, analyze before changing, research feature
在确定进行变更前，对某个想法或代码库区域进行调查和分析。
触发方式：
/sdd-explore <topic>
、explore、investigate codebase、analyze before changing、research feature

Purpose

目的

The exploration phase is optional but valuable. Its goal is to understand the terrain before proposing changes. It creates no code and modifies nothing. It only reads and analyzes.
Use it when:
  • The request is vague or complex
  • You are unsure of the scope of the change
  • You want to understand the impact before committing
  • There are multiple possible approaches
探索阶段是可选但极具价值的。其目标是在提出变更前先了解现有情况。此阶段不会生成代码，也不会修改任何内容，仅进行读取和分析。
在以下场景中使用：
  • 请求模糊或复杂
  • 你不确定变更的范围
  • 你希望在确定变更前了解其影响
  • 存在多种可行方案

Process

流程

Skill Resolution

技能解析

When the orchestrator launches this sub-agent, it resolves the skill path using:
1. .claude/skills/sdd-explore/SKILL.md     (project-local — highest priority)
2. ~/.claude/skills/sdd-explore/SKILL.md   (global catalog — fallback)
Project-local skills override the global catalog. See 
docs/SKILL-RESOLUTION.md
for the full algorithm.
当编排器（orchestrator）启动此子代理（sub-agent）时，它会通过以下路径解析技能：
1. .claude/skills/sdd-explore/SKILL.md     (项目本地 — 优先级最高)
2. ~/.claude/skills/sdd-explore/SKILL.md   (全局目录 — 备选)
项目本地技能会覆盖全局目录中的技能。完整算法请参阅
docs/SKILL-RESOLUTION.md
。

Step 0 — Load project context + Spec context preload

步骤0 — 加载项目上下文 + 规格上下文预加载

Follow 
skills/_shared/sdd-phase-common.md
Section F (Project Context Load) and Section G (Spec Context Preload). Both are non-blocking.
遵循
skills/_shared/sdd-phase-common.md
中的F部分（项目上下文加载）和G部分（规格上下文预加载）。这两个步骤均为非阻塞式。

Step 0 sub-step — Handoff context preload

步骤0子步骤 — 交接上下文预加载

This sub-step is non-blocking: any failure (missing file, unreadable file, no slug) MUST produce at most an INFO-level note. This sub-step MUST NOT produce 
status: blocked
or 
status: failed
.
  1. Resolve the change slug from the invocation context.
  2. Check whether a proposal already exists in engram: 
    mem_search(query: "sdd/<slug>/proposal")
    .
  3. If absent: skip silently — log 
    INFO: no pre-seeded proposal found — proceeding without handoff context.
  4. If present: retrieve via 
    mem_get_observation(id)
    . Treat its content as supplemental intent enrichment:
    • It informs what the explore should prioritize, not what the codebase shows.
    • It MUST NOT override live codebase findings.
    • Log: 
      Handoff context loaded from engram: sdd/<slug>/proposal
  5. When loaded, include a 
    ## Handoff Context
    section in the exploration output (placed before 
    ## Current State
    ) summarizing:
    • Decision that triggered the change
    • Goal and success criteria from the seeded proposal
    • Explore targets listed in the proposal
    • Constraints ("do not do" items)
此子步骤为非阻塞式：任何失败（文件缺失、无法读取、无标识）最多只能生成INFO级别的提示。此子步骤不得返回
status: blocked
或
status: failed
。
  1. 从调用上下文中解析变更标识（change slug）。
  2. 检查engram中是否已存在提案：
    mem_search(query: "sdd/<slug>/proposal")
    。
  3. 若不存在：静默跳过 — 记录
    INFO: no pre-seeded proposal found — proceeding without handoff context.
  4. 若存在：通过
    mem_get_observation(id)
    获取内容。将其视为补充意图信息：
    • 它用于指导探索的优先级，而非替代代码库的实际情况。
    • 不得覆盖代码库的实时发现结果。
    • 记录：
      Handoff context loaded from engram: sdd/<slug>/proposal
  5. 加载完成后，在探索输出中添加
    ## 交接上下文
    章节 （置于
    ## 当前状态
    之前），总结以下内容：
    • 触发变更的决策
    • 预存提案中的目标和成功标准
    • 提案中列出的探索目标
    • 约束条件（“禁止操作”项）

Step 1 — Understand the request

步骤1 — 理解请求

I classify what type of exploration is needed:
  • New feature: What already exists? Where would it fit?
  • Bug: Where is the problem? What is the root cause?
  • Refactor: What code is affected? What are the risks?
  • Integration: What exists to connect? What is missing?
我会对所需的探索类型进行分类：
  • 新功能：当前已有哪些内容？新功能应置于何处？
  • Bug修复：问题出在哪里？根本原因是什么？
  • 重构：哪些代码会受影响？存在哪些风险？
  • 集成：已有哪些可用于连接的内容？缺少什么？

Step 2 — Branch Diff scan

步骤2 — 分支差异扫描

This step is non-blocking: any failure (git unavailable, no working tree, empty diff) MUST produce at most an INFO-level note. This step MUST NOT produce 
status: blocked
or 
status: failed
.
  1. Run 
    git status --short
    to identify modified, staged, and untracked files in the current working tree.
  2. Filter results to files relevant to the domain being explored (match by path prefix, filename, or keyword overlap with the change name).
  3. Classify each file as: 
    modified
    , 
    staged
    , 
    deleted
    , or 
    untracked
    .
  4. Write output to the 
    ## Branch Diff
    section.
If git is unavailable or diff is empty: log 
INFO: branch diff unavailable or empty — skipping Branch Diff section
and include an empty 
## Branch Diff
section with that note.
Output format:
undefined
此步骤为非阻塞式：任何失败（Git不可用、无工作树、差异为空）最多只能生成INFO级别的提示。此步骤不得返回
status: blocked
或
status: failed
。
  1. 运行
    git status --short
    以识别当前工作树中已修改、已暂存和未跟踪的文件。
  2. 筛选出与探索领域相关的文件（通过路径前缀、文件名或与变更名称的关键词匹配）。
  3. 将每个文件分类为：
    modified
    （已修改）、
    staged
    （已暂存）、
    deleted
    （已删除）或
    untracked
    （未跟踪）。
  4. 将结果写入
    ## 分支差异
    章节。
若Git不可用或差异为空：记录
INFO: branch diff unavailable or empty — skipping Branch Diff section
，并在空的
## 分支差异
章节中包含该提示。
输出格式：
undefined

Branch Diff

Branch Diff

Files modified in current branch relevant to this change:
  • path/to/file.ts (modified)
  • path/to/other.ts (staged, pending deletion)
  • path/to/new-file.ts (untracked)
undefined
Files modified in current branch relevant to this change:
  • path/to/file.ts (modified)
  • path/to/other.ts (staged, pending deletion)
  • path/to/new-file.ts (untracked)
undefined

Step 3 — Prior Attempts archive scan

步骤3 — 过往尝试归档扫描

This step is non-blocking: any failure MUST produce at most an INFO-level note.
Search engram for prior archived changes related to this topic:
mem_search(query: "sdd/archive-report", project: "{project}")
Filter results by keyword overlap with the current change slug. For each related result, retrieve via 
mem_get_observation(id)
to check outcome.
Write output to the 
## Prior Attempts
section.
Output format:
undefined
此步骤为非阻塞式：任何失败最多只能生成INFO级别的提示。
在engram中搜索与当前主题相关的过往归档变更：
mem_search(query: "sdd/archive-report", project: "{project}")
通过与当前变更标识的关键词匹配筛选结果。对于每个相关结果，通过
mem_get_observation(id)
获取内容以查看结果。
将结果写入
## 过往尝试
章节。
输出格式：
undefined

Prior Attempts

Prior Attempts

Prior archived changes related to this topic:
  • auth-flow-v1: COMPLETED
  • auth-flow-v2: ABANDONED
[or: "No prior attempts found."]
undefined
Prior archived changes related to this topic:
  • auth-flow-v1: COMPLETED
  • auth-flow-v2: ABANDONED
[or: "No prior attempts found."]
undefined

Step 4 — Contradiction Analysis

步骤4 — 矛盾分析

This step is non-blocking: contradictions are informational and MUST NOT cause 
status: blocked
or 
status: failed
. At most, contradictions may cause 
status: warning
.
  1. Compare the user's stated intent (from change description and any pre-seeded proposal) against:
    • Loaded feature files from Step 0 (behavioral contracts)
    • Prior attempt outcomes from Step 3
    • ai-context/
      files
  2. For each potential contradiction detected, classify severity:
    • CERTAIN: the user says "remove X" AND a loaded spec explicitly states "X MUST exist" — no ambiguity
    • UNCERTAIN: the user intent implies removing or changing X, but there is no explicit spec contract — ambiguous
  3. Assign impact level: 
    INFO
    (minimal), 
    WARNING
    (notable), 
    CRITICAL
    (breaking)
  4. Write output to the 
    ## Contradiction Analysis
    section.
  5. Do NOT block exploration — the status remains 
    ok
    unless contradictions are severe enough to set 
    status: warning
    .
Output format:
undefined
此步骤为非阻塞式：矛盾仅作为信息提示，不得导致
status: blocked
或
status: failed
。最多只能将状态设为
status: warning
。
  1. 将用户声明的意图（来自变更描述和任何预存提案）与以下内容进行对比：
    • 步骤0中加载的功能文件（行为契约）
    • 步骤3中的过往尝试结果
    • ai-context/
      目录下的文件
  2. 对于检测到的每个潜在矛盾，分类其严重程度：
    • 确定（CERTAIN）：用户要求“移除X”，且已加载的规格明确规定“X必须存在” — 无歧义
    • 不确定（UNCERTAIN）：用户意图暗示要移除或修改X，但无明确的规格契约 — 存在歧义
  3. 分配影响级别：
    INFO
    （极小）、
    WARNING
    （显著）、
    CRITICAL
    （破坏性）
  4. 将结果写入
    ## 矛盾分析
    章节。
  5. 不得中断探索 — 除非矛盾严重到需要设置
    status: warning
    ，否则状态保持
    ok
    。
输出格式：
undefined

Contradiction Analysis

Contradiction Analysis

Contradictions detected between user intent and existing context:
  • Item: [feature or behavior name] Status: CERTAIN|UNCERTAIN — [explanation of what contradicts what] Severity: INFO|WARNING|CRITICAL Resolution: [suggested resolution or "Requires user confirmation"]
[or: "No contradictions detected."]
undefined
Contradictions detected between user intent and existing context:
  • Item: [feature or behavior name] Status: CERTAIN|UNCERTAIN — [explanation of what contradicts what] Severity: INFO|WARNING|CRITICAL Resolution: [suggested resolution or "Requires user confirmation"]
[or: "No contradictions detected."]
undefined

Step 5 — Investigate the codebase

步骤5 — 调查代码库

I read real code following this hierarchy:
  1. Entry points of the affected area
  2. Files related to the functionality
  3. Existing tests (they reveal expected behavior)
  4. Relevant configurations
  5. ai-context/architecture.md
    if it exists (to understand past decisions)
我会按照以下优先级读取实际代码：
  1. 受影响区域的入口点
  2. 与功能相关的文件
  3. 现有测试（它们能揭示预期行为）
  4. 相关配置
  5. 若存在
    ai-context/architecture.md
    （用于理解过往决策）

Step 6 — Analyze approaches

步骤6 — 分析方案

For each possible approach I generate a comparison table:
ApproachProsConsEffortRisk
[Option A]Low/Medium/HighLow/Medium/High
[Option B]
对于每个可行方案，我会生成一个对比表格：
方案优点缺点工作量风险
[选项A]低/中/高低/中/高
[选项B]

Step 7 — Identify risks and dependencies

步骤7 — 识别风险和依赖项

  • Code that would break with the change
  • Dependencies that would need to be updated
  • Tests that would fail
  • Non-obvious side effects
  • 变更可能会破坏的代码
  • 需要更新的依赖项
  • 可能会失败的测试
  • 不明显的副作用

Step 8 — Save if a change name was specified

步骤8 — 若指定了变更名称则保存

Pre-save naming check (non-blocking):
If 
<change-name>
starts with 
explore-
, warn before writing:
Note: The change name "[change-name]" starts with "explore-".
Standalone explore folders (e.g. explore-fy-topic) are not part of a full SDD planning cycle
and will not be automatically cleaned up or archived.

If you intend this as a full SDD change, use a descriptive slug and continue with /sdd-propose:
  /sdd-propose <description>   <- starts the planning cycle from proposal

If you intend this as a one-off investigation, proceed as-is.
This warning is informational only — writing proceeds regardless of the name.
If invoked as 
/sdd-explore <change-name>
, I persist the exploration artifact.
Write: Call 
mem_save
with 
topic_key: sdd/{change-name}/explore
, 
type: architecture
, 
project: {project}
, content = full exploration markdown. Do NOT write any file.
  • If no change name provided: log 
    INFO: no change name — skipping artifact persistence
    and skip.
  • If Engram MCP is not reachable: skip persistence. Return exploration content inline only.
Persisted artifact (compact — only what downstream phases consume):
markdown
undefined
预保存命名检查（非阻塞式）：
如果
<change-name>
以
explore-
开头，保存前会发出警告：
Note: The change name "[change-name]" starts with "explore-".
Standalone explore folders (e.g. explore-fy-topic) are not part of a full SDD planning cycle
and will not be automatically cleaned up or archived.

If you intend this as a full SDD change, use a descriptive slug and continue with /sdd-propose:
  /sdd-propose <description>   <- starts the planning cycle from proposal

If you intend this as a one-off investigation, proceed as-is.
此警告仅作为信息提示 — 无论名称如何，保存都会继续。
如果以
/sdd-explore <change-name>
调用，我会持久化探索工件。
写入操作： 调用
mem_save
，参数为
topic_key: sdd/{change-name}/explore
、
type: architecture
、
project: {project}
，content为完整的探索markdown文档。不得写入任何文件。
  • 若未提供变更名称：记录
    INFO: no change name — skipping artifact persistence
    并跳过此步骤。
  • 若无法连接到Engram MCP：跳过持久化操作。仅返回内联的探索内容。
持久化工件（精简版 — 仅包含下游阶段所需内容）：
markdown
undefined

Exploration: [topic]

Exploration: [topic]

Current State

Current State

[2-3 sentence summary of what currently exists in the codebase]
[2-3 sentence summary of what currently exists in the codebase]

Branch Diff

Branch Diff

  • [path/to/file] (modified|staged|deleted|untracked) [or: "No relevant changes in current branch."]
  • [path/to/file] (modified|staged|deleted|untracked) [or: "No relevant changes in current branch."]

Prior Attempts

Prior Attempts

  • [or: "None found."]
  • [or: "None found."]

Contradiction Analysis

Contradiction Analysis

  • [Item]: [CERTAIN|UNCERTAIN] — [one-line explanation] [or: "No contradictions detected."]
  • [Item]: [CERTAIN|UNCERTAIN] — [one-line explanation] [or: "No contradictions detected."]

Recommendation

Recommendation

[Recommended approach in 1-2 sentences]
[Recommended approach in 1-2 sentences]

Ready for Proposal

Ready for Proposal

[Yes/No — and why if No]

**Conversational output** (shown to user but NOT persisted):

The full analysis — including Affected Areas table, Analyzed Approaches with pros/cons/effort/risk, Identified Risks with mitigations, Open Questions, and Handoff Context — is presented in the conversational response to the orchestrator. This content is ephemeral and does not need to survive across sessions.

---
[Yes/No — and why if No]

**对话输出**（展示给用户但不持久化）：

完整分析 — 包括受影响区域表格、带有优缺点/工作量/风险的分析方案、已识别风险及缓解措施、未解决问题和交接上下文 — 会在给编排器的对话响应中呈现。此内容为临时内容，无需跨会话保存。

---

Output to Orchestrator

输出给编排器

json
{
  "status": "ok|warning|blocked",
  "summary": "Analysis of [topic]: [2-3 lines of the main finding]",
  "artifacts": ["engram:sdd/{change-name}/explore"],
  "next_recommended": ["sdd-propose"],
  "risks": ["[risk if found]"]
}
json
{
  "status": "ok|warning|blocked",
  "summary": "Analysis of [topic]: [2-3 lines of the main finding]",
  "artifacts": ["engram:sdd/{change-name}/explore"],
  "next_recommended": ["sdd-propose"],
  "risks": ["[risk if found]"]
}

Rules

规则

  • I ONLY read code — I never modify anything in this phase
  • I read real code, never assume or invent
  • If I find something unexpected (technical debt, inconsistencies), I report it
  • I keep the analysis concise: the goal is to inform, not to write a thesis
  • If the exploration reveals that the change is trivial, I say so clearly
  • 我仅读取代码 — 此阶段绝不会修改任何内容
  • 我读取实际代码，绝不假设或编造
  • 若发现意外情况（技术债务、不一致性），我会进行报告
  • 分析保持简洁：目标是提供信息，而非撰写论文
  • 若探索发现变更非常简单，我会明确说明