investigation-workflow · diff
v1.0.0 to v2.0.0
112 added, 317 removed. Audit A to A.
---
name: investigation-workflow
- version: 1.0.0
+ version: 2.0.0
description: |
- 6-phase investigation workflow for understanding existing systems. Auto-activates for research tasks.
- Optimized for exploration and understanding, not implementation. Includes parallel agent deployment
- for efficient deep dives and automatic knowledge capture to prevent repeat investigations.
+ 6-phase investigation workflow for understanding existing systems. Normally executed
+ as a sub-recipe by dev-orchestrator/smart-orchestrator. Supports direct invocation
+ via recipe runner for standalone use.
auto_activates:
- "investigate how"
- "explain the architecture"
- "understand the system"
- "how does"
- "why does"
- "analyze"
- "research"
- "explore"
explicit_triggers:
- - /amplihack:investigation-workflow
- - /investigate
+ - /amplihack:investigation
confirmation_required: true
skip_confirmation_if_explicit: true
token_budget: 4000
---
# Investigation Workflow Skill
+ ## Relationship to Dev Orchestrator
+
+ **Normal execution path**: This workflow is invoked as a sub-recipe by the
+ `dev-orchestrator` skill via `smart-orchestrator`. You do NOT normally need
+ to activate this skill directly.
+
+ ```
+ User request → dev-orchestrator → smart-orchestrator recipe
+ → investigation-workflow recipe (this skill's recipe)
+ ```
+
+ **Direct invocation** is supported as a compatibility path when the
+ dev-orchestrator is unavailable or when explicitly requested. In that case,
+ use the recipe runner (see Execution Instructions below).
+
## Workflow Graph
```mermaid
flowchart TD
INIT[Initialize Tracking] --> P1
subgraph P1["Phase 1: Scope Definition"]
SCOPE[scope-definition<br/>prompt-writer agent] --> AMB{Has ambiguities?}
AMB -->|yes| CLARIFY[clarify-ambiguities<br/>ambiguity agent]
AMB -->|no| P1_OUT[Scope defined]
CLARIFY --> P1_OUT
end
subgraph P2["Phase 2: Exploration Strategy"]
STRAT[exploration-strategy<br/>architect agent] --> PAST[check-past-investigations<br/>patterns agent]
PAST --> HIST{Historical context needed?}
HIST -->|yes| ARCH[historical-research<br/>knowledge-archaeologist]
HIST -->|no| P2_OUT[Strategy ready]
ARCH --> P2_OUT
end
subgraph P3["Phase 3: Parallel Deep Dives"]
DD1[deep-dive-primary<br/>architect agent]
DD2[deep-dive-secondary<br/>patterns agent]
DD3[deep-dive-tertiary<br/>architect agent]
DD4{Specialist needed?}
DD4 -->|yes| DDS[deep-dive-specialist<br/>security agent]
DD1 & DD2 & DD3 --> CONSOL[consolidate-findings<br/>patterns agent]
DDS --> CONSOL
end
subgraph P4["Phase 4: Verification"]
HYP[formulate-hypotheses<br/>architect agent] --> EXEC[execute-verification<br/>architect agent]
EXEC --> VAL[validate-verification<br/>reviewer agent]
end
subgraph P5["Phase 5: Synthesis"]
PAT[identify-patterns<br/>patterns agent] --> SYN[synthesis<br/>architect agent]
SYN --> VSYN[validate-synthesis<br/>reviewer agent]
end
subgraph P6["Phase 6: Knowledge Capture"]
DISC[update-discoveries] --> PATN{New patterns?}
PATN -->|yes| UPAT[update-patterns]
PATN -->|no| RPT[create-investigation-report]
UPAT --> RPT
end
P1 --> P2 --> P3 --> P4 --> P5 --> P6
RPT --> TRANS[transition-guidance<br/>patterns agent]
TRANS --> EFF[efficiency-report]
EFF --> FINAL[final-output]
TRANS --> TDEV{Transition to dev?}
- TDEV -->|yes| DW[Resume DEFAULT_WORKFLOW<br/>at Step 4 or 5]
+ TDEV -->|yes| DW[Launch default-workflow<br/>recipe via recipe runner]
TDEV -->|no| DONE[Investigation Complete]
```
## 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.
+ 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.
+ It is normally executed as a sub-recipe by the `dev-orchestrator` via `smart-orchestrator`,
+ but can also be invoked directly via the recipe runner.
+
+ ## Canonical Sources
+
+ - **Executable source (recipe)**: `amplifier-bundle/recipes/investigation-workflow.yaml`
+ - **Reference documentation**: `.claude/workflow/INVESTIGATION_WORKFLOW.md`
+
+ The recipe YAML is the authoritative execution definition. The `.md` file serves as
+ human-readable reference documentation for the workflow phases.
+
+ ## Execution Instructions
+
+ ### Normal path (via dev-orchestrator)
+
+ If you reached this skill via `dev-orchestrator` / `smart-orchestrator`, the recipe
+ runner is already managing execution. **Do not re-invoke the recipe runner.** The
+ orchestrator handles the full lifecycle including goal-seeking reflection loops.
+
+ ### Direct invocation (standalone)
+
+ If this skill is activated directly (not via dev-orchestrator), you MUST use the
+ recipe runner — **do NOT read the .md file and follow phases manually**:
+
+ ```python
+ from amplihack.recipes import run_recipe_by_name
+
+ result = run_recipe_by_name(
+ "investigation-workflow",
+ user_context={
+ "task_description": "TASK_DESCRIPTION_HERE",
+ "repo_path": ".",
+ },
+ progress=True,
+ )
+ ```
+
+ Or via shell:
+
+ ```bash
+ cd /path/to/repo && env -u CLAUDECODE \
+ AMPLIHACK_HOME=/path/to/amplihack PYTHONPATH=${AMPLIHACK_HOME:-~/.amplihack}/src python3 -c "
+ from amplihack.recipes import run_recipe_by_name
+ result = run_recipe_by_name('investigation-workflow', user_context={
+ 'task_description': '''TASK_DESCRIPTION_HERE''',
+ 'repo_path': '.',
+ }, progress=True)
+ print(f'Recipe result: {result}')
+ "
+ ```
+
+ **Do NOT** read `INVESTIGATION_WORKFLOW.md` and follow phases manually. The recipe
+ runner enforces phase ordering, agent deployment, and quality gates that manual
+ execution cannot replicate.
+
+ ### Preferred: Use dev-orchestrator instead
+
+ For most tasks, invoke `Skill(skill="dev-orchestrator")` or use `/dev <task>` rather
+ than activating this skill directly. The dev-orchestrator adds goal-seeking reflection,
+ workstream decomposition, and adaptive error recovery on top of this workflow.
+
## 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):
+ **Development Tasks** (use default-workflow recipe instead):
- "Implement OAuth support"
- "Build a new API endpoint"
- "Add feature X"
- "Fix 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
## The 6-Phase Investigation Workflow
### Phase 1: Scope Definition
**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
-
### Phase 2: Exploration Strategy
**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
-
### Phase 3: Parallel Deep Dives
**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
-
### Phase 4: Verification & Testing
**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
-
### Phase 5: Synthesis
**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**:
-
- 1. **Executive Summary**: 2-3 sentence answer to main question
- 2. **Detailed Explanation**: Complete explanation with supporting evidence
- 3. **Visual Aids**: Diagrams showing system flow, architecture, etc.
- 4. **Key Insights**: Non-obvious discoveries or patterns
- 5. **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
-
### Phase 6: Knowledge Capture
**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
- ## 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/`
-
## Transitioning to Development Workflow
- **After investigation completes**, if the task requires implementation (not just understanding), transition to **DEFAULT_WORKFLOW.md**:
-
- 1. **Resume at Step 4** (Research and Design) with the knowledge gained from investigation
- 2. **Or resume at Step 5** (Implement the Solution) if the investigation already provided clear design guidance
- 3. **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
+ **After investigation completes**, if the task requires implementation, the
+ `dev-orchestrator` handles the transition automatically via its goal-seeking
+ reflection loop. If running standalone, transition by launching the
+ `default-workflow` recipe:
- 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)
+ ```python
+ run_recipe_by_name("default-workflow", user_context={
+ "task_description": "Implement findings from investigation...",
+ "repo_path": ".",
+ }, progress=True)
```
- **When to Transition**:
-
- - Investigation reveals implementation is needed
- - User explicitly requested both investigation + development
- - Follow-up work identified during knowledge capture
-
- ## 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**:
-
- 1. **Scope Definition** prevents scope creep and wandering
- 2. **Exploration Strategy** prevents random unproductive exploration
- 3. **Parallel Deep Dives** maximize information gathering speed
- 4. **Verification Phase** catches misunderstandings early
- 5. **Synthesis** ensures all questions answered
- 6. **Knowledge Capture** prevents repeat investigations
-
- ## Comparison to 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
-
- ### Differences (Investigation vs. Development)
-
- | 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) |
-
- ### 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 |
-
- ## Integration with UltraThink
-
- **UltraThink Workflow Detection**: When `/ultrathink` is invoked, it automatically detects investigation tasks using keywords and suggests this workflow.
+ ## Integration with Dev Orchestrator
- **Automatic Workflow Suggestion**:
+ The `dev-orchestrator` automatically detects investigation tasks using keywords
+ and routes them to this workflow's recipe:
```
- User: "/ultrathink investigate how authentication works"
+ User: "/dev 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
+ dev-orchestrator: Classified as Investigation → launching investigation-workflow recipe
+ → Recipe runner executes 6-phase investigation workflow
+ → Results feed into goal-seeking reflection loop
```
- ## Customization
-
- To customize this workflow:
-
- 1. Edit `~/.amplihack/.claude/workflow/INVESTIGATION_WORKFLOW.md` to modify, add, or remove phases
- 2. Adjust agent deployment strategies for your needs
- 3. Add project-specific investigation patterns
- 4. Update efficiency targets based on your metrics
-
- Changes take effect immediately for future investigations.
-
- ## 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
+ For hybrid tasks (investigate + implement), the dev-orchestrator decomposes into
+ parallel workstreams: one running `investigation-workflow`, another running
+ `default-workflow`.
## 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"
-
## Related Resources
- - **Source Workflow**: `~/.amplihack/.claude/workflow/INVESTIGATION_WORKFLOW.md` (complete 436-line specification)
- - **Knowledge Extraction**: Use knowledge-extractor skill after investigations to capture learnings
- - **Agent Catalog**: `~/.amplihack/.claude/agents/CATALOG.md` for all available agents
- - **Pattern Library**: `~/.amplihack/.claude/context/PATTERNS.md` for reusable investigation patterns
+ - **Recipe (executable)**: `amplifier-bundle/recipes/investigation-workflow.yaml`
+ - **Reference docs**: `.claude/workflow/INVESTIGATION_WORKFLOW.md`
+ - **Dev Orchestrator**: `.claude/skills/dev-orchestrator/`
+ - **Default Workflow**: `.claude/skills/default-workflow/`
+ - **Agent Catalog**: `.claude/agents/amplihack/` directory
+ - **Pattern Library**: `.claude/context/PATTERNS.md`