investigation-workflow

# Investigation Workflow 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.

## 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"

## 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