investigation-workflow

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Investigation Workflow Skill

调查工作流Skill

Purpose

目的

This skill provides a systematic 6-phase workflow for investigating and understanding existing systems, codebases, and architectures. Unlike development workflows optimized for implementation, this workflow is optimized for exploration, understanding, and knowledge capture.

本Skill提供了一套系统化的6阶段工作流，用于调查和了解现有系统、代码库与架构。与专为实现优化的开发工作流不同，本工作流专为探索、理解和知识捕获而设计。

When to Use This Skill

适用场景

Investigation Tasks (use this workflow):

"Investigate how the authentication system works"
"Explain the neo4j memory integration"
"Understand why CI is failing consistently"
"Analyze the reflection system architecture"
"Research what hooks are triggered during session start"

Development Tasks (use DEFAULT_WORKFLOW.md instead):

"Implement OAuth support"
"Build a new API endpoint"
"Add feature X"
"Fix bug Y"

调查任务（使用本工作流）：

"调查认证系统的工作原理"
"解释neo4j内存集成机制"
"理解CI持续失败的原因"
"分析反射系统的架构"
"研究会话启动时触发的钩子"

开发任务（改用DEFAULT_WORKFLOW.md）：

"实现OAuth支持"
"构建新的API端点"
"添加功能X"
"修复Bug Y"

Core Philosophy

核心理念

Exploration First: Define scope and strategy before diving into code Parallel Deep Dives: Deploy multiple agents simultaneously for efficient information gathering Verification Required: Test understanding through practical application Knowledge Capture: Document findings to prevent repeat investigations

先探索后深入：在深入代码前定义范围与策略 并行深度调研：同时部署多个Agent以高效收集信息 需验证：通过实际应用测试理解程度 知识捕获：记录发现以避免重复调查

The 6-Phase Investigation Workflow

6阶段调查工作流

Phase 1: Scope Definition

阶段1：范围定义

Purpose: Define investigation boundaries and success criteria before any exploration.

Tasks:

FIRST: Identify explicit user requirements - What specific questions must be answered?
Use prompt-writer agent to clarify investigation scope
Use ambiguity agent if questions are unclear
Define what counts as "understanding achieved"
List specific questions that must be answered
Set boundaries: What's in scope vs. out of scope
Estimate investigation depth needed (surface-level vs. deep dive)

Success Criteria:

Clear list of questions to answer
Defined scope boundaries
Measurable success criteria (e.g., "can explain system flow", "can diagram architecture")

Deliverables:

Investigation scope document with:
- Core questions to answer
- Success criteria
- Scope boundaries (what's included/excluded)
- Estimated depth and timeline

目的：在开始任何探索前，定义调查边界与成功标准。

任务：

首要任务：明确用户的具体需求——必须回答哪些特定问题？
使用prompt-writer agent来明确调查范围
若问题不清晰，使用ambiguity agent
定义“理解达成”的判定标准
列出必须回答的具体问题
设置边界：哪些属于范围，哪些不属于
评估所需的调查深度（表面级 vs 深度调研）

成功标准：

清晰的待回答问题列表
明确的范围边界
可衡量的成功标准（例如：“能够解释系统流程”、“能够绘制架构图”）

交付物：

调查范围文档，包含：
- 需回答的核心问题
- 成功标准
- 范围边界（包含/排除内容）
- 预估的调查深度与时间线

Phase 2: Exploration Strategy

阶段2：探索策略

Purpose: Plan which agents to deploy and what to investigate, preventing inefficient random exploration.

Tasks:

Use architect agent to design exploration strategy
Use patterns agent to check for similar past investigations
Identify key areas to explore (code paths, configurations, documentation)
Select specialized agents for parallel deployment in Phase 3
Create investigation roadmap with priorities
Identify potential dead ends to avoid
Plan verification approach (how to test understanding)

Agent Selection Guidelines:

For code understanding: analyzer, patterns agents
For system architecture: architect, api-designer agents
For performance issues: optimizer, analyzer agents
For security concerns: security, patterns agents
For integration flows: integration, database agents

Success Criteria:

Clear exploration roadmap
List of agents to deploy in Phase 3
Prioritized investigation areas

Deliverables:

Exploration strategy document with:
- Investigation roadmap
- Agent deployment plan for Phase 3
- Priority order for exploration
- Expected outputs from each exploration

目的：规划要部署的Agent和调查方向，避免低效的随机探索。

任务：

使用architect agent设计探索策略
使用patterns agent检查是否有类似的过往调查案例
确定需要探索的关键领域（代码路径、配置、文档）
为阶段3的并行部署选择专业Agent
创建带有优先级的调查路线图
识别需要避开的潜在死胡同
规划验证方法（如何测试理解程度）

Agent选择指南：

代码理解：analyzer、patterns agent
系统架构：architect、api-designer agent
性能问题：optimizer、analyzer agent
安全问题：security、patterns agent
集成流程：integration、database agent

成功标准：

清晰的探索路线图
阶段3要部署的Agent列表
按优先级排序的调查领域

交付物：

探索策略文档，包含：
- 调查路线图
- 阶段3的Agent部署计划
- 探索的优先级顺序
- 各探索环节的预期输出

Phase 3: Parallel Deep Dives

阶段3：并行深度调研

Purpose: Deploy multiple exploration agents simultaneously to gather information efficiently.

CRITICAL: This phase uses PARALLEL EXECUTION by default.

Tasks:

Deploy selected agents in PARALLEL based on Phase 2 strategy

Common parallel patterns:

[analyzer(module1), analyzer(module2), analyzer(module3)]

- Multiple code areas

```
[analyzer, patterns, security]
```
- Multiple perspectives on same area
```
[architect, database, integration]
```
- System architecture exploration

Each agent explores their assigned area independently
Collect findings from all parallel explorations
Identify connections and dependencies between findings
Note any unexpected discoveries or anomalies

Parallel Agent Examples:

Investigation: "How does the reflection system work?"
→ [analyzer(~/.amplihack/.claude/tools/amplihack/hooks/), patterns(reflection), integration(logging)]

Investigation: "Why is CI failing?"
→ [analyzer(ci-config), patterns(ci-failures), integration(github-actions)]

Investigation: "Understand authentication flow"
→ [analyzer(auth-module), security(auth), patterns(auth), integration(external-auth)]

Success Criteria:

All planned agents deployed and completed
Findings from each exploration collected
Connections between findings identified

Deliverables:

Findings report with:
- Summary from each parallel exploration
- Code paths and flow diagrams
- Architectural insights
- Unexpected discoveries
- Open questions for verification

目的：同时部署多个探索Agent，高效收集信息。

关键提示：本阶段默认使用并行执行。

任务：

根据阶段2的策略，并行部署选定的Agent

常见并行模式：

[analyzer(module1), analyzer(module2), analyzer(module3)]

- 多代码区域调研

```
[analyzer, patterns, security]
```
- 同一区域的多视角调研
```
[architect, database, integration]
```
- 系统架构探索

每个Agent独立探索分配的领域
收集所有并行探索的发现
识别各发现之间的关联与依赖
记录任何意外发现或异常情况

并行Agent示例：

调查任务：“反射系统如何工作？”
→ [analyzer(~/.amplihack/.claude/tools/amplihack/hooks/), patterns(reflection), integration(logging)]

调查任务：“CI为何失败？”
→ [analyzer(ci-config), patterns(ci-failures), integration(github-actions)]

调查任务：“理解认证流程”
→ [analyzer(auth-module), security(auth), patterns(auth), integration(external-auth)]

成功标准：

所有计划部署的Agent均已完成任务
收集到各探索环节的发现
识别出各发现之间的关联

交付物：

发现报告，包含：
- 各并行探索环节的摘要
- 代码路径与流程图
- 架构洞察
- 意外发现
- 待验证的开放问题

Phase 4: Verification & Testing

阶段4：验证与测试

Purpose: Test and validate understanding through practical application.

Tasks:

Create hypotheses based on Phase 3 findings
Design practical tests to verify understanding:
- Trace specific code paths manually
- Examine logs and outputs
- Test edge cases and assumptions
- Verify configuration effects
Run verification tests
Document what was tested and results
Identify gaps in understanding
Refine hypotheses based on test results
Repeat verification for any unclear areas

Verification Examples:

Understanding: "Authentication uses JWT tokens"
Verification: Trace actual token creation and validation in code

Understanding: "CI fails because of dependency conflict"
Verification: Check CI logs, reproduce locally, verify fix works

Understanding: "Reflection analyzes all user messages"
Verification: Examine reflection logs, trace message processing

Success Criteria:

All hypotheses tested
Understanding verified through practical tests
Gaps in understanding identified and filled

Deliverables:

Verification report with:
- Tests performed
- Results and observations
- Confirmed understanding
- Remaining gaps or uncertainties

目的：通过实际应用测试和验证理解程度。

任务：

根据阶段3的发现创建假设
设计实际测试以验证理解：
- 手动追踪特定代码路径
- 检查日志与输出
- 测试边缘情况与假设
- 验证配置的影响
执行验证测试
记录测试内容与结果
识别理解中的差距
根据测试结果完善假设
对不清晰的领域重复验证

验证示例：

理解：“认证使用JWT令牌”
验证：在代码中追踪实际的令牌创建与验证流程

理解：“CI因依赖冲突失败”
验证：检查CI日志，本地复现问题，验证修复方案有效

理解：“反射会分析所有用户消息”
验证：检查反射日志，追踪消息处理流程

成功标准：

所有假设均已测试
通过实际验证确认理解正确
识别并填补了理解中的差距

交付物：

验证报告，包含：
- 执行的测试内容
- 结果与观察
- 已确认的理解
- 剩余的差距或不确定性

Phase 5: Synthesis

阶段5：综合整理

Purpose: Compile findings into coherent explanation that answers original questions.

Tasks:

Use reviewer agent to check completeness of findings
Use patterns agent to identify reusable patterns discovered
Synthesize findings from Phases 3-4 into coherent explanation
Create visual artifacts (diagrams, flow charts) if helpful
Answer each question from Phase 1 scope definition
Identify what worked well vs. what was unexpected
Note any assumptions or uncertainties remaining
Prepare clear explanation suitable for user

Synthesis Outputs:

Executive Summary: 2-3 sentence answer to main question
Detailed Explanation: Complete explanation with supporting evidence
Visual Aids: Diagrams showing system flow, architecture, etc.
Key Insights: Non-obvious discoveries or patterns
Remaining Unknowns: What's still unclear or uncertain

Success Criteria:

All Phase 1 questions answered
Explanation is clear and complete
Findings supported by evidence from verification
Visual aids clarify complex areas

Deliverables:

Investigation report with all 5 synthesis outputs
Ready for knowledge capture in Phase 6

目的：将发现整理为连贯的解释，回答最初的问题。

任务：

使用reviewer agent检查发现的完整性
使用patterns agent识别可复用的模式
将阶段3-4的发现整理为连贯的解释
如有帮助，创建可视化工件（图表、流程图）
回答阶段1范围定义中的每个问题
识别哪些环节进展顺利，哪些超出预期
记录仍存在的假设或不确定性
为用户准备清晰的解释内容

综合输出：

执行摘要：用2-3句话回答核心问题
详细解释：带有支持证据的完整解释
可视化辅助：展示系统流程、架构等的图表
关键洞察：非显而易见的发现或模式
未知事项：仍不清晰或不确定的内容

成功标准：

阶段1的所有问题均已回答
解释清晰且完整
发现得到验证环节的证据支持
可视化辅助澄清了复杂领域

交付物：

包含所有5项综合输出的调查报告
已为阶段6的知识捕获做好准备

Phase 6: Knowledge Capture

阶段6：知识捕获

Purpose: Create durable documentation so this investigation never needs to be repeated.

Tasks:

Store discoveries in memory using

store_discovery()

from

amplihack.memory.discoveries

Update .claude/context/PATTERNS.md if reusable patterns found
Create or update relevant documentation files
Add inline code comments for critical understanding
Optional: Create GitHub issue for follow-up improvements
Optional: Update architecture diagrams if needed
Ensure future investigators can find this knowledge easily

Documentation Guidelines:

markdown

undefined

目的：创建持久化文档，避免未来重复进行相同调查。

任务：

使用

amplihack.memory.discoveries

中的

store_discovery()

将发现存储到内存中

若发现可复用模式，更新
```
.claude/context/PATTERNS.md
```
创建或更新相关文档文件
为关键理解添加内联代码注释
可选：创建GitHub议题以跟进改进
可选：如有需要，更新架构图
确保未来的调查人员能够轻松找到这些知识

文档指南：

markdown

undefined

Discovery: [Brief Title]

发现：[简短标题]

Context: What was investigated and why Key Findings:

Main insight 1
Main insight 2
- Supporting Evidence: Links to code, logs, or verification tests
- Implications: How this affects the project
- Related Patterns: Links to similar patterns in PATTERNS.md


**Success Criteria**:

- Discoveries stored in memory for future reference
- Relevant documentation files updated
- Knowledge is discoverable by future investigators
- No information loss

**Deliverables**:

- Discoveries stored in memory
- Updated PATTERNS.md (if applicable)
- Updated project documentation
- Optional: GitHub issues for improvements
- Investigation session log in `~/.amplihack/.claude/runtime/logs/`

背景：调查的内容与原因 关键发现：

核心洞察1
核心洞察2
- 支持证据：指向代码、日志或验证测试的链接
- 影响：对项目的影响
- 相关模式：指向PATTERNS.md中类似模式的链接


**成功标准**：

- 发现已存储到内存中以备未来参考
- 相关文档文件已更新
- 知识可被未来的调查人员检索到
- 无信息丢失

**交付物**：

- 存储到内存中的发现
- 更新后的PATTERNS.md（如适用）
- 更新后的项目文档
- 可选：用于改进的GitHub议题
- 存储在`~/.amplihack/.claude/runtime/logs/`中的调查会话日志

Transitioning to Development Workflow

过渡到开发工作流

After investigation completes, if the task requires implementation (not just understanding), transition to DEFAULT_WORKFLOW.md:

Resume at Step 4 (Research and Design) with the knowledge gained from investigation
Or resume at Step 5 (Implement the Solution) if the investigation already provided clear design guidance
Use investigation findings from memory (via
```
get_recent_discoveries()
```
) and session logs to inform design decisions

Example Hybrid Workflow:

User: "/ultrathink investigate how authentication works, then add OAuth support"

Phase 1: Investigation
→ Run INVESTIGATION_WORKFLOW.md (6 phases)
→ Complete understanding of existing auth system
→ Store findings in memory via discoveries adapter

Phase 2: Development
→ Transition to DEFAULT_WORKFLOW.md
→ Resume at Step 4 (Research and Design)
→ Use investigation insights to design OAuth integration
→ Continue through Step 15 (implementation → testing → PR)

When to Transition:

Investigation reveals implementation is needed
User explicitly requested both investigation + development
Follow-up work identified during knowledge capture

调查完成后，若任务需要实现（而非仅理解），则过渡到DEFAULT_WORKFLOW.md：

从步骤4继续（研究与设计），利用调查获得的知识
或从步骤5继续（实现解决方案），如果调查已提供清晰的设计指导
使用内存中的调查发现（通过
```
get_recent_discoveries()
```
）和会话日志为设计决策提供信息

混合工作流示例：

用户："/ultrathink 调查认证系统的工作原理，然后添加OAuth支持"

阶段1：调查
→ 执行INVESTIGATION_WORKFLOW.md（6阶段）
→ 完全理解现有认证系统
→ 通过discoveries适配器将发现存储到内存中

阶段2：开发
→ 过渡到DEFAULT_WORKFLOW.md
→ 从步骤4继续（研究与设计）
→ 利用调查洞察设计OAuth集成方案
→ 继续执行至步骤15（实现→测试→PR）

过渡时机：

调查显示需要进行实现工作
用户明确要求同时进行调查与开发
知识捕获环节中识别出后续工作

Efficiency Targets

效率目标

Target Efficiency: This workflow targets a 30-40% reduction in message count compared to ad-hoc investigation.

Ad-Hoc Approach	Investigation Workflow
70-90 messages	40-60 messages
Frequent backtracking	Planned exploration
Redundant investigation	Parallel deep dives
Unclear scope	Explicit scope definition
Lost knowledge	Documented insights

Efficiency Gains Come From:

Scope Definition prevents scope creep and wandering
Exploration Strategy prevents random unproductive exploration
Parallel Deep Dives maximize information gathering speed
Verification Phase catches misunderstandings early
Synthesis ensures all questions answered
Knowledge Capture prevents repeat investigations

目标效率：与临时调查相比，本工作流旨在减少30-40%的消息数量。

临时方法	调查工作流
70-90条消息	40-60条消息
频繁回溯	有计划的探索
重复调查	并行深度调研
范围不明确	明确的范围定义
知识丢失	已记录的洞察

效率提升来源：

范围定义防止范围蔓延与无目的探索
探索策略避免随机的无效探索
并行深度调研最大化信息收集速度
验证阶段及早发现误解
综合整理确保所有问题得到回答
知识捕获避免重复调查

Comparison to DEFAULT_WORKFLOW.md

与DEFAULT_WORKFLOW.md的对比

Similarities (Structural Consistency)

相似点（结构一致性）

Both workflows share core principles:

Explicit phases with clear deliverables
Agent-driven execution at each phase
Quality gates preventing premature progression
Knowledge capture and documentation
TodoWrite tracking for progress management

两个工作流共享核心原则：

具有明确交付物的清晰阶段
各阶段由Agent驱动执行
防止过早推进的质量门
知识捕获与文档记录
用于进度管理的TodoWrite追踪

Differences (Investigation vs. Development)

差异点（调查 vs 开发）

Aspect	Investigation Workflow	DEFAULT_WORKFLOW.md
Goal	Understanding	Implementation
Phases	6 phases	Multi-step workflow
Execution	Exploration-first	Implementation-first
Parallel Focus	Phase 3 (Deep Dives)	Various steps
Testing	Understanding verification	Code validation
Deliverable	Documentation	Working code
Git Usage	Optional	Required (branches, PRs)

维度	调查工作流	DEFAULT_WORKFLOW.md
目标	理解系统	实现功能
阶段	6个阶段	多步骤工作流
执行方式	先探索	先实现
并行重点	阶段3（深度调研）	多个步骤
测试内容	验证理解程度	代码验证
交付物	文档	可运行代码
Git使用	可选	必需（分支、PR）

Phase Mapping (For User Familiarity)

阶段映射（便于用户理解）

Investigation Phase	DEFAULT_WORKFLOW Equivalent	Purpose
Phase 1: Scope Definition	Step 1: Requirements Clarification	Define what success looks like
Phase 2: Exploration Strategy	Step 4: Research and Design	Plan the approach
Phase 3: Parallel Deep Dives	Step 5: Implementation	Execute the plan (explore vs. build)
Phase 4: Verification	Steps 7-8: Testing	Validate results
Phase 5: Synthesis	Step 11: Review	Ensure quality and completeness
Phase 6: Knowledge Capture	Step 15: Cleanup	Make results durable

调查阶段	DEFAULT_WORKFLOW对应步骤	目的
阶段1：范围定义	步骤1：需求澄清	定义成功的标准
阶段2：探索策略	步骤4：研究与设计	规划执行方案
阶段3：并行深度调研	步骤5：实现	执行方案（探索 vs 构建）
阶段4：验证	步骤7-8：测试	验证结果
阶段5：综合整理	步骤11：评审	确保质量与完整性
阶段6：知识捕获	步骤15：清理	确保成果持久化

Integration with UltraThink

与UltraThink的集成

UltraThink Workflow Detection: When

/ultrathink

is invoked, it automatically detects investigation tasks using keywords and suggests this workflow.

Automatic Workflow Suggestion:

User: "/ultrathink investigate how authentication works"

UltraThink: Detected investigation task. Using INVESTIGATION_WORKFLOW.md
→ Reading workflow from .claude/workflow/INVESTIGATION_WORKFLOW.md
→ Following 6-phase investigation workflow
→ Starting Phase 1: Scope Definition

UltraThink工作流检测：调用

/ultrathink

时，系统会通过关键词自动检测调查任务，并推荐本工作流。

自动工作流推荐：

用户："/ultrathink 调查认证系统的工作原理"

UltraThink：检测到调查任务。正在使用INVESTIGATION_WORKFLOW.md
→ 从~/.amplihack/.claude/workflow/INVESTIGATION_WORKFLOW.md读取工作流
→ 执行6阶段调查工作流
→ 开始阶段1：范围定义

Customization

自定义

To customize this workflow:

Edit

~/.amplihack/.claude/workflow/INVESTIGATION_WORKFLOW.md

to modify, add, or remove phases

Adjust agent deployment strategies for your needs
Add project-specific investigation patterns
Update efficiency targets based on your metrics

Changes take effect immediately for future investigations.

如需自定义本工作流：

编辑

~/.amplihack/.claude/workflow/INVESTIGATION_WORKFLOW.md

以修改、添加或移除阶段

根据需求调整Agent部署策略
添加项目特定的调查模式
根据你的指标更新效率目标

更改会立即对未来的调查生效。

Success Metrics

成功指标

Track these metrics to validate workflow effectiveness:

Message Count: Target 30-40% reduction vs. ad-hoc (to be validated)
Investigation Time: Track time to completion
Knowledge Reuse: How often memory retrieval prevents repeat work
Completeness: Percentage of investigations with full documentation
User Satisfaction: Clear understanding achieved

跟踪以下指标以验证工作流的有效性：

消息数量：目标比临时调查减少30-40%（待验证）
调查时间：跟踪完成时间
知识复用：内存检索避免重复工作的频率
完整性：完成完整文档的调查比例
用户满意度：是否达成清晰的理解

Key Principles

核心原则

Scope first, explore second - Define boundaries before diving in
Parallel exploration is key - Deploy multiple agents simultaneously in Phase 3
Verify understanding - Test your hypotheses in Phase 4
Capture knowledge - Always store discoveries in memory in Phase 6
This workflow optimizes for understanding, not implementation

When in doubt about investigation vs. development:

Investigation: "I need to understand X"
Development: "I need to build/fix/implement X"

先定范围，后做探索：深入前先定义边界
并行探索是关键：阶段3同时部署多个Agent
验证理解：阶段4测试你的假设
捕获知识：阶段6始终将发现存储到内存中
本工作流专为理解优化，而非实现

当不确定是调查还是开发时：

调查：“我需要理解X”
开发：“我需要构建/修复/实现X”

investigation-workflow

Original

Translation

Investigation Workflow Skill

调查工作流Skill

Purpose

目的

When to Use This Skill

适用场景

Core Philosophy

核心理念

The 6-Phase Investigation Workflow

6阶段调查工作流

Phase 1: Scope Definition

阶段1：范围定义

Phase 2: Exploration Strategy

阶段2：探索策略

Phase 3: Parallel Deep Dives

阶段3：并行深度调研

Phase 4: Verification & Testing

阶段4：验证与测试

Phase 5: Synthesis

阶段5：综合整理

Phase 6: Knowledge Capture

阶段6：知识捕获

Discovery: [Brief Title]

发现：[简短标题]

Transitioning to Development Workflow

过渡到开发工作流

Efficiency Targets

效率目标

Comparison to DEFAULT_WORKFLOW.md

与DEFAULT_WORKFLOW.md的对比

Similarities (Structural Consistency)

相似点（结构一致性）

Differences (Investigation vs. Development)

差异点（调查 vs 开发）

Phase Mapping (For User Familiarity)

阶段映射（便于用户理解）

Integration with UltraThink

与UltraThink的集成

Customization

自定义

Success Metrics

成功指标

Key Principles

核心原则

Related Resources

相关资源