Codebase Analysis Skill

Systematically explore and understand existing codebases, including entry point discovery, dependency tracing, pattern detection, and technical debt identification.

Variables

Variable	Default	Description
ANALYSIS_DEPTH	standard	`quick` (5min), `standard` (30min), `deep` (1hr+)
OUTPUT_FORMAT	markdown	`markdown`, `json`, `c4`
INCLUDE_DEBT	true	Include technical debt assessment
INCLUDE_DIAGRAMS	true	Generate C4 diagrams

Instructions

MANDATORY - Follow the Workflow steps below in order. Do not skip steps.

•Start with entry points, not random files
•Trace dependencies before analyzing patterns
•Document findings as you go

Red Flags - STOP and Reconsider

If you're about to:

•Analyze random files without finding entry points first
•Make architectural claims without tracing dependencies
•Skip pattern detection before identifying anti-patterns
•Report technical debt without severity classification

STOP -> Read the appropriate cookbook file -> Follow the workflow -> Then proceed

Workflow

• Quick Assessment: Project size, structure, config files
• CHECKPOINT: Identify entry points (read cookbook/entry-point-discovery.md)
• Trace dependencies from entry points
• Detect architectural patterns
• CHECKPOINT: Verify pattern detection before anti-pattern search
• Identify anti-patterns and technical debt
• Document findings with C4 diagrams (if INCLUDE_DIAGRAMS)

Cookbook

Entry Point Discovery

•IF: Starting analysis of unfamiliar codebase
•THEN: Read cookbook/entry-point-discovery.md
•RESULT: List of main entry points by framework

Dependency Tracing

•IF: Need to understand how modules connect
•THEN: Read cookbook/dependency-tracing.md
•RESULT: Import chains, dependency graph

Pattern Detection

•IF: Need to identify architectural style
•THEN: Read cookbook/pattern-detection.md
•RESULT: Identified patterns (MVC, Layered, etc.)

Technical Debt Identification

•IF: Assessing code quality and debt
•THEN: Read cookbook/debt-identification.md
•RESULT: Prioritized debt inventory

Quick Reference

Entry Points by Stack

Stack	Look For
Node.js	`package.json` main/bin, `index.js`, `server.js`
TypeScript	`tsconfig.json`, `src/index.ts`
Python	`__main__.py`, `app.py`, `wsgi.py`
Go	`main.go`, `cmd/*/main.go`
React	`src/index.tsx`, `pages/_app.tsx`

See reference/framework-patterns.md for complete list.

Common Patterns

Pattern	Directory Signs
MVC	`models/`, `views/`, `controllers/`
Layered	`presentation/`, `business/`, `data/`
Hexagonal	`domain/`, `ports/`, `adapters/`
Microservices	`services//`, `packages//`

Output

Standard Report Format

markdown

# Codebase Analysis: [Project Name]

## Overview
- **Size**: X files, Y lines
- **Primary Language**: TypeScript
- **Framework**: Next.js
- **Architecture**: [Pattern]

## Entry Points
1. `src/pages/_app.tsx` - Application root
2. `src/api/` - API routes

## Key Dependencies
- [External deps list]

## Architecture Diagram
[C4 diagram if INCLUDE_DIAGRAMS]

## Technical Debt (if INCLUDE_DEBT)
| Issue | Severity | Location |
|-------|----------|----------|
| ... | High | ... |