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