/investigate

allowed-tools: Task, WebFetch, Read, Grep, Bash(rg:*), Bash(fd:*), Bash(gdate:*), Bash(jq:*), Bash(git:status), Bash(git:branch), Bash(pwd:*)
name: "Investigate"
description: "Conduct thorough investigation using codebase analysis and web research for optimal solutions"
author: "wcygan"
tags: ["analyze","research"]
version: "1.0.0"
created_at: "2025-07-14T00:00:00Z"
updated_at: "2025-07-14T00:00:00Z"

/investigate

Conduct thorough investigation of a topic, technology, or approach using codebase analysis and web research to determine optimal solutions with up-to-date information.

Context

• Session ID: !`gdate +%s%N`
• Investigation target: $ARGUMENTS
• Current directory: !`pwd`
• Project structure: !`fd . -t d -d 2 | head -10 || echo "No subdirectories"`
• Technology stack: !`fd -e json -e toml -e xml -e txt . | rg "(deno\.json|package\.json|Cargo\.toml|pom\.xml|requirements\.txt|composer\.json)" | head -5 || echo "No technology files detected"`
• Git repository: !`git status --porcelain | head -5 || echo "Not a git repository"`
• Current branch: !`git branch --show-current 2>/dev/null || echo "No git repository"`

Usage

/investigate [topic or question]

Your Task

STEP 1: Investigation Setup and Context Analysis

• Create session state file: /tmp/investigate-state-$SESSION_ID.json
• Parse investigation topic: $ARGUMENTS
• Identify key terms and concepts from the investigation target
• Determine investigation scope and depth requirements
• Save initial context to state file

STEP 2: Codebase Discovery (Parallel Sub-Agent Approach)

FOR complex investigations requiring extensive codebase analysis:

**CRITICAL: Deploy parallel sub-agents for comprehensive investigation (7-9x faster research)**

IMMEDIATELY launch 8 specialized investigation agents:

• **Agent 1: Implementation Pattern Analysis**: Search for existing implementations and architectural patterns
• Focus: Current implementations, design patterns, code structure, architecture decisions
• Tools: Code pattern analysis, architecture mapping, implementation discovery
• Output: Existing solution catalog with pattern assessment and architectural insights

• **Agent 2: Configuration & Dependencies Analysis**: Analyze configuration files and dependency ecosystem
• Focus: Configuration files, dependency versions, environment settings, build configurations
• Tools: Configuration analysis, dependency tree analysis, version compatibility checking
• Output: Configuration landscape with dependency analysis and compatibility assessment

• **Agent 3: Documentation & Knowledge Analysis**: Review documentation and architectural decisions
• Focus: READMEs, architectural docs, decision records, inline documentation
• Tools: Documentation analysis, knowledge extraction, decision tracking
• Output: Knowledge baseline with documentation gaps and architectural context

• **Agent 4: Test Coverage & Validation Analysis**: Examine test coverage and validation approaches
• Focus: Test strategies, coverage metrics, validation patterns, quality assurance
• Tools: Test analysis, coverage assessment, validation pattern discovery
• Output: Testing insights with coverage analysis and validation strategy assessment

• **Agent 5: Integration & Component Analysis**: Map component relationships and integration points
• Focus: Service boundaries, API contracts, data flows, integration patterns
• Tools: Component mapping, integration analysis, API contract discovery
• Output: Integration landscape with component relationships and interaction patterns

• **Agent 6: Industry Standards & Best Practices Research**: Research current industry standards and emerging trends
• Focus: Industry benchmarks, best practices, emerging trends, standard compliance
• Tools: Web research, standards analysis, trend monitoring, benchmark comparison
• Output: Industry landscape with standards compliance and trend analysis

• **Agent 7: Technology Comparison & Alternative Analysis**: Compare alternative technologies and approaches
• Focus: Alternative solutions, technology comparisons, trade-off analysis, migration paths
• Tools: Technology research, comparison analysis, migration assessment, trade-off evaluation
• Output: Technology options with comparative analysis and migration considerations

• **Agent 8: Risk Assessment & Future-Proofing Analysis**: Evaluate risks and future-proofing considerations
• Focus: Risk factors, future trends, technology longevity, support ecosystem
• Tools: Risk analysis, future trend assessment, ecosystem evaluation, sustainability analysis
• Output: Risk assessment with future-proofing recommendations and mitigation strategies

**Sub-Agent Coordination:**

• Each agent saves findings to `/tmp/investigation-agents-$SESSION_ID/`
• Parallel execution provides 7-9x speed improvement over sequential research
• Cross-agent correlation provides comprehensive multi-dimensional analysis
• Results synthesized into cohesive investigation report with confidence scoring

ELSE (simple investigations):

Execute sequential codebase analysis:

• Search existing implementations: rg "$ARGUMENTS" --type-add 'code:*.{rs,go,java,ts,js,py}' -t code
• Find related configuration: rg "$ARGUMENTS" --type yaml --type json --type toml
• Look for documentation: fd "README|ARCHITECTURE|DESIGN" --type f | xargs rg -l "$ARGUMENTS"

STEP 3: Pattern Discovery and Architecture Analysis

TRY:

• Find implementation patterns: rg "impl._$ARGUMENTS|class.*$ARGUMENTS|interface._$ARGUMENTS" -A 5 -B 2
• Analyze dependencies: rg "$ARGUMENTS" package.json Cargo.toml go.mod pom.xml requirements.txt
• Check test coverage: fd "test|spec" --type f | xargs rg -l "$ARGUMENTS"
• Document architectural relationships and data flows

CATCH (pattern_not_found):

• Note absence of existing implementations
• Document opportunity for greenfield implementation
• Focus investigation on industry best practices

STEP 4: Web Research and Techn