Code Investigator
Systematic codebase investigation using parallel subagents. Discover all features, analyze risks, and produce a prioritized action report.
Workflow
Phase 1: Feature Discovery
Use the Task tool with subagent_type=Explore to map the entire project:
- Identify project type (framework, language, architecture pattern)
- List all features/modules with file locations
- Map dependencies (package.json, requirements.txt, go.mod, etc.)
- Identify entry points, routes, API endpoints
- Note configuration files, environment setup, CI/CD
Output a structured feature inventory:
## Feature Inventory
| # | Feature/Module | Files | Description |
|---|---------------|-------|-------------|
| 1 | Authentication | src/auth/* | OAuth + session |
| 2 | Product CRUD | src/products/* | Admin API |
...
Present this inventory to the user before proceeding to Phase 2.
Phase 2: Parallel Investigation
Launch multiple Task subagents in a single message to investigate concurrently. Each subagent focuses on one investigation area. See references/investigation-areas.md for detailed checklists per area.
Required subagents (launch all in parallel):
| Subagent | Type | Focus |
|----------|------|-------|
| Security Auditor | tech-lead | Vulnerabilities, injection risks, auth gaps, secret exposure |
| Dead Code Detector | Explore | Unused exports, unreachable code, orphan files, unused dependencies |
| Architecture Reviewer | tech-lead | Pattern violations, circular deps, coupling issues, missing abstractions |
| Error & Edge Case Analyzer | Explore | Missing error handling, unhandled promises, race conditions |
| Dependency Auditor | Bash | npm audit, outdated packages, license issues, duplicate deps |
| Test Coverage Analyzer | Explore | Missing tests, untested critical paths, test quality |
Optional subagents (based on project type):
| Subagent | Type | When |
|----------|------|------|
| Performance Profiler | tech-lead | Web apps, APIs with DB queries |
| TypeScript Strictness | Explore | TS projects with any usage |
| API Contract Checker | Explore | Projects with REST/GraphQL APIs |
| Accessibility Auditor | Explore | Frontend projects |
Each subagent prompt must include:
- The feature inventory from Phase 1
- Specific checklist items from references/investigation-areas.md
- Instruction to rate each finding: CRITICAL / HIGH / MEDIUM / LOW
- Instruction to provide file path and line number for each finding
Phase 3: Report Synthesis
Collect all subagent results and compile into a single prioritized report.
Report Structure
# Code Investigation Report
**Project:** [name] | **Date:** [date] | **Files Analyzed:** [count]
## Executive Summary
[2-3 sentences: overall health, top concerns, immediate actions needed]
## Critical Findings (Act Immediately)
| # | Finding | Category | File:Line | Impact | Recommendation |
|---|---------|----------|-----------|--------|----------------|
## High Priority
| # | Finding | Category | File:Line | Impact | Recommendation |
|---|---------|----------|-----------|--------|----------------|
## Medium Priority
| # | Finding | Category | File:Line | Impact | Recommendation |
|---|---------|----------|-----------|--------|----------------|
## Low Priority / Improvements
| # | Finding | Category | File:Line | Impact | Recommendation |
|---|---------|----------|-----------|--------|----------------|
## Dead Code & Redundancies
| # | Item | Type | File:Line | Safe to Remove? |
|---|------|------|-----------|-----------------|
## Missing Functionality
| # | Gap | Why It Matters | Suggested Implementation |
|---|-----|----------------|--------------------------|
## Dependency Health
| Package | Current | Latest | Risk | Action |
|---------|---------|--------|------|--------|
## Metrics Summary
- Total findings: X (Critical: X, High: X, Medium: X, Low: X)
- Dead code items: X
- Missing features: X
- Vulnerable dependencies: X
Sorting Rules
- CRITICAL: Security vulnerabilities, data loss risks, crashes in production
- HIGH: Bugs likely to affect users, missing auth checks, unhandled errors in critical paths
- MEDIUM: Code smells, minor security issues, performance concerns, missing tests
- LOW: Style issues, minor refactoring opportunities, nice-to-have improvements
Key Guidelines
- Never guess - always verify by reading actual code before reporting a finding
- Include file path and line number for every finding
- Distinguish between confirmed issues and potential concerns
- Do not report style preferences as issues unless they cause real problems
- Group related findings to avoid duplicate reports
- If a subagent finds nothing in its area, report that as a positive signal