home / skills / toilahuongg / shopify-agents-kit / code-investigator

code-investigator skill

needs review

This skill performs comprehensive codebase investigation by mapping features, then running parallel subagents to audit risks, dead code, and missing

npx playbooks add skill toilahuongg/shopify-agents-kit --skill code-investigator

Review the files below or copy the command above to add this skill to your agents.

Files (2)

SKILL.md

5.3 KB

---
name: code-investigator
description: Comprehensive code investigation and audit tool. Discovers all project features, then dispatches parallel subagents to analyze issues, risks, dead code, missing functionality, and redundancies. Produces a prioritized risk report. Use this skill when the user asks to "investigate code", "audit project", "find risks", "check code quality", "analyze codebase", "what's wrong with this code", "project health check", "code review entire project", "find dead code", "find redundant code", or any request for a thorough codebase analysis.
---

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

1. Identify project type (framework, language, architecture pattern)
2. List all features/modules with file locations
3. Map dependencies (package.json, requirements.txt, go.mod, etc.)
4. Identify entry points, routes, API endpoints
5. 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](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

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

1. **CRITICAL**: Security vulnerabilities, data loss risks, crashes in production
2. **HIGH**: Bugs likely to affect users, missing auth checks, unhandled errors in critical paths
3. **MEDIUM**: Code smells, minor security issues, performance concerns, missing tests
4. **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

Overview

This skill performs a systematic, end-to-end investigation and audit of a codebase. It discovers features and entry points, runs parallel subagents to analyze security, dead code, architecture, errors, dependencies, and tests, and delivers a prioritized, actionable risk report. Use it to get a clear plan for immediate fixes and medium-term improvements.

How this skill works

First, it maps the project by identifying framework, modules, entry points, routes, dependencies, and configuration to produce a feature inventory. Next, it launches multiple parallel subagents, each with a focused checklist (security, dead code, architecture, error handling, dependencies, tests) that report findings with file paths, line numbers, and severity ratings. Finally, it synthesizes subagent outputs into a single prioritized report with remediation recommendations and sorting by criticality.

When to use it

You want a full project health check before a release or handoff
You need a prioritized list of security vulnerabilities and fixes
You want to locate and safely remove dead or redundant code
You need actionable dependency and license risk assessment
You want a consolidated assessment of missing tests and error handling

Best practices

Provide repository access and specify the primary entrypoints or build commands
Allow the initial feature inventory review before running full investigations
Choose optional subagents appropriate to the project (profiling, TS strictness, API contracts)
Require file path and line number for every finding to enable quick triage
Treat confirmed findings separate from potential concerns; never report unverified issues

Example use cases

Pre-release audit to catch security and crash risks before shipping
Onboarding: produce a feature inventory and risk map for new maintainers
Refactoring sprint: identify dead code and coupling hot spots to reduce scope
Open-source maintainers: surface vulnerable dependencies and license issues
QA lead: get prioritized list of missing tests and critical unhandled errors

FAQ

How long does an investigation take?

Duration varies with repo size; small projects (minutes), medium (tens of minutes), large monorepos (hours). The feature inventory is presented first to scope work.

Will the skill modify my code?

No. The process inspects and reports only. Remediation recommendations include suggested patches but no automatic code changes.

How are severities determined?

Each subagent rates findings as CRITICAL / HIGH / MEDIUM / LOW following defined sorting rules: critical = data loss or exploitable vuln; high = user-impacting bugs or auth gaps; medium = performance or missing tests; low = style or refactor notes.