Codebase Investigation Skill

You perform deep analysis of an existing codebase to generate comprehensive PROJECT.md context.

Arguments

Investigation Process

Step 1: Project Structure

# Get current git hash for context tracking
git -C {project_path} rev-parse HEAD

# List top-level structure
ls -la {project_path}

# Get directory tree (excluding common ignores)
find {project_path} -type d \
  -not -path '*/\.*' \
  -not -path '*/node_modules/*' \
  -not -path '*/venv/*' \
  -not -path '*/.venv/*' \
  -not -path '*/__pycache__/*' \
  -not -path '*/dist/*' \
  -not -path '*/build/*' \
  | head -100

Step 2: Tech Stack Detection

Check for package/config files:

# Check multiple patterns
ls {project_path}/pyproject.toml {project_path}/requirements.txt {project_path}/setup.py 2>/dev/null
ls {project_path}/package.json {project_path}/tsconfig.json 2>/dev/null
ls {project_path}/go.mod {project_path}/Cargo.toml 2>/dev/null

Read package files to extract:

• Language and version
• Framework (FastAPI, React, Go Chi, etc.)
• Database ORM (SQLAlchemy, Drizzle, GORM)
• Key dependencies

Step 3: Feature Discovery

Based on detected framework, look for features:

FastAPI/Python:

grep -r "@router\." {project_path}/src --include="*.py" -l
grep -r "@app\." {project_path}/src --include="*.py" -l

Express/Node:

grep -r "router\." {project_path}/src --include="*.ts" --include="*.js" -l

React:

find {project_path}/src -name "*.tsx" -path "*/components/*" -o -name "*.tsx" -path "*/pages/*"

Step 4: API Endpoint Extraction

FastAPI:

# Look for patterns like:
@router.get("/users")
@router.post("/auth/login")

Read files and extract:

• Method (GET, POST, PUT, DELETE)
• Path
• Request/response types from type hints

Express/TanStack:

// Look for patterns like:
router.get('/users', handler)
app.post('/auth/login', handler)

Step 5: Schema/Model Extraction

SQLAlchemy:

# Look for class definitions inheriting from Base
class User(Base):
    __tablename__ = "users"

Drizzle:

// Look for table definitions
export const users = pgTable('users', {...})

Extract:

• Model name
• Table name
• Fields with types
• Relationships (foreign keys)

Step 6: Pattern Analysis

Identify common patterns:

• File naming conventions
• Import patterns
• Error handling approach
• Authentication mechanism
• State management (frontend)

Step 7: Generate PROJECT.md

Create PROJECT.md at {project_path}/PROJECT.md:

# Project: {detected name}

## Overview
{Inferred from README.md or code structure}

## Architecture

### Tech Stack
{Detected stack}

### Component Structure
{Directory tree with annotations}

### Key Patterns
{Detected patterns}

## Context Metadata
<project-context version="1.0">
  <meta>
    <last-updated>{now}</last-updated>
    <last-context-hash>{git hash}</last-context-hash>
  </meta>

  <features>
    {Discovered features}
  </features>

  <api-registry>
    {Extracted endpoints}
  </api-registry>

  <schema-registry>
    {Extracted models}
  </schema-registry>
</project-context>

Step 8: Create CRD Directory

mkdir -p {project_path}/docs/crd

Depth Levels

Quick (5-10 minutes)

• Project structure
• Tech stack from package files
• Main entry points
• README overview

Medium (15-20 minutes) - Default

• All of Quick
• Feature inventory from routes/components
• API endpoint extraction
• Database model extraction
• Basic pattern identification

Deep (30+ minutes)

• All of Medium
• Full dependency graph
• Test coverage analysis
• Integration point mapping
• Detailed pattern analysis
• Code quality assessment

Output

After completion, report:

Investigation complete.

PROJECT.md generated at: {project_path}/PROJECT.md

Summary:
- Tech Stack: {stack}
- Features: {count} identified
- API Endpoints: {count} documented
- Database Models: {count} cataloged
- Context Hash: {hash}

docs/crd/ directory created for future CRDs.

Error Handling