investigate

name	investigate
description	Use for open-ended exploration and investigation of unfamiliar codebases, systems, or problems. Complements systematic-debugging (which is for known errors). Use investigate when: "how does X work", "understand this codebase", "map this system". Triggers: "investigate", "explore", "understand how", "map the codebase".
allowed-tools	["Bash","Read","Write","Edit","Grep","Glob"]
when_to_use	Use for open-ended exploration of unfamiliar code: "how does X work", "map this system". Complements systematic-debugging (which requires a known error). NOT for known bugs — use systematic-debugging.
produces	null
consumes	null
dispatch-agent	explorer

Preamble (Core)

Status protocol — end every session with one of: DONE (evidence provided) · DONE_WITH_CONCERNS (list each) · BLOCKED (state what blocks you) · NEEDS_CONTEXT (state what you need).

Auto-advance — pipeline: THINK → PLAN → REVIEW → BUILD → VERIFY → RELEASE. Only human gate is spec approval at THINK. On DONE at other stages, print [STAGE] DONE -> advancing to [NEXT-STAGE] and invoke the next skill. On any non-DONE status at any stage, STOP.

Output directory — all artifacts go in docs/superomni/<kind>/<kind>-[branch]-[session]-[date].md. See CLAUDE.md for the full directory map.

TACIT-DENSE — before high-tacit decisions, classify D1 (domain expertise) · D2 (user-facing UX) · D3 (team culture) · D4 (novel pattern). On hit, output TACIT-DENSE [D#]: [question] — My default: [recommendation]. See reference for actions.

Anti-sycophancy — take a position on every significant question. Name flaws directly. No filler ("that's interesting", "you might consider", "that could work").

Telemetry (local only) — at session end, log bin/analytics-log. Nothing leaves the machine.

See preamble-ref.md for detailed protocols.

Investigate

Goal: Build a shared, accurate mental model of an unfamiliar system, codebase, or problem space.

Distinction from systematic-debugging:

• investigate → you don't have a specific error; you're building understanding
• systematic-debugging → you have a specific error and need to find root cause

Phase 1: Orient

Start by understanding the big picture before any details.

# Project structure overview
find . -type f -name "*.md" | head -20  # documentation
ls -la                                   # top-level files
cat README.md 2>/dev/null | head -50     # quick overview
cat package.json 2>/dev/null             # or Makefile, go.mod, etc.

# Technology stack
ls -la *.json *.yaml *.toml *.rb *.py *.go 2>/dev/null | head -20

# Size estimate
find . -type f | grep -v ".git\|node_modules\|dist\|build" | wc -l

Output: "System overview: ..." — 3-5 sentence description of what this system is.

Phase 2: Map Entry Points

Find where the system starts and where users/callers interact with it:

# Find main entry points
grep -rn "main()\|app.listen\|server.listen\|createApp\|bootstrap" . \
  --include="*.js" --include="*.ts" --include="*.py" --include="*.go" \
  -l | head -10

# Find API routes
grep -rn "router\.\|app\.get\|app\.post\|@route\|@app\.route" . \
  --include="*.js" --include="*.ts" --include="*.py" -l | head -10

# Find CLI commands
grep -rn "commander\|yargs\|argparse\|click\|cobra" . \
  --include="*.js" --include="*.ts" --include="*.py" --include="*.go" \
  -l | head -10

Phase 3: Trace a Representative Path

Pick ONE representative flow (the most common user action) and trace it end to end:

1. Input — where does it enter the system?
2. Processing — what transforms it?
3. Storage/Side effects — what does it change?
4. Output — what does the user/caller receive back?

# Trace a specific function through the codebase
FUNCTION_NAME="handleRequest"
grep -rn "${FUNCTION_NAME}" . --include="*.js" --include="*.ts" -A 3 | head -30

Phase 4: Identify Key Modules

Map the key components and their responsibilities:

SYSTEM MAP
════════════════════════════════════════
Entry points:    [list]
Core modules:    [list with 1-line descriptions]
Data stores:     [DBs, caches, files]
External deps:   [APIs, services, libraries]
Test coverage:   [rough %]
════════════════════════════════════════

Phase 5: Find Hotspots and Risk Areas

# Most-changed files (hotspots)
git log --oneline | wc -l  # commit count
git log --pretty=format: --name-only | sort | uniq -c | sort -rn | head -20

# Largest files (complexity hotspots)
find . -name "*.js" -o -name "*.ts" -o -name "*.py" | \
  xargs wc -l 2>/dev/null | sort -rn | head -10

# Files with most TODOs
grep -rn "TODO\|FIXME\|HACK\|XXX" . \
  --include="*.js" --include="*.ts" --include="*.py" | wc -l

Phase 6: Document Findings

Write a brief investigation summary:

INVESTIGATION REPORT
════════════════════════════════════════
Subject:     [what was investigated]
Time spent:  [~N minutes]

Overview:
  [3-5 sentences describing the system]

Key findings:
  - [finding 1]
  - [finding 2]
  - [finding 3]

Hotspots/risks:
  - [file/area]: [why it's risky]

Unknown/unclear:
  - [thing that wasn't resolved]

Recommended next steps:
  1. [action based on findings]
  2. [action based on findings]

Status: DONE | NEEDS_CONTEXT
════════════════════════════════════════

Useful Investigation Commands

# Count lines of code by file type
find . -name "*.js" | xargs wc -l | tail -1  # JavaScript
find . -name "*.py" | xargs wc -l | tail -1  # Python

# Find all configuration files
find . -name "*.env*" -o -name "*.config.*" -o -name "*.yaml" -o -name "*.toml" | \
  grep -v "node_modules\|.git" | head -20

# Find database schema
find . -name "*.sql" -o -name "schema.*" -o -name "*migration*" | \
  grep -v "node_modules\|.git" | head -10

# Understand test coverage
find . -name "*.test.*" -o -name "*.spec.*" -o -name "test_*.py" | \
  grep -v "node_modules" | wc -l