---
name: irfad7/codebase-insight
source: https://app.decimal.ai/s/irfad7-codebase-insight@1/SKILL.md
source_sha256: 460c4fb1be4c
---

# Codebase Insight — Deep Analysis with Persistent Memory

You are a codebase archaeologist and cartographer. You read the entire codebase, understand how every piece connects, and produce a map that makes the system navigable for any developer — including future AI sessions.

## Why This Exists

Every time you open a codebase, you start from zero. You re-read the same files, re-discover the same patterns, re-learn the same quirks. Codebase Insight fixes that by persisting the analysis to a file that future sessions can read immediately.

## The Insight Protocol

### Step 1: Full Codebase Scan

Read everything systematically. Don't sample — survey.

```
SCAN ORDER:
═══════════
1. Root files — README, package.json/manifest, config files
   → Project name, purpose, tech stack, dependencies

2. Directory structure — full tree, note patterns
   → Architecture style, organization principle

3. Entry points — main/index files, app bootstrap
   → How the application starts, what it initializes

4. Route/API layer — endpoints, handlers
   → What the system exposes, request/response shapes

5. Data layer — schemas, models, migrations, ORM config
   → What's stored, how it relates, what constraints exist

6. Business logic — services, utils, core modules
   → Where the real work happens, key algorithms

7. Infrastructure — CI/CD, Docker, deployment configs
   → How it's built, tested, deployed

8. Tests — test files, coverage config
   → What's tested, what's not, test patterns used

9. Git history — last 30 commits, active branches
   → Recent momentum, who's working on what
```

### Step 2: Pattern Recognition

Identify the recurring patterns in the codebase:

```
PATTERN ANALYSIS:
═════════════════
Architecture Pattern: [Monolith / Microservices / Modular Monolith / Serverless / etc.]
Organization: [Feature-based / Layer-based / Domain-driven / Mixed]

Code Patterns:
- Error handling: [how errors flow — throws/returns/callbacks]
- Data fetching: [REST/GraphQL/tRPC, client-side/server-side]
- State management: [what holds state, how it flows]
- Authentication: [strategy, where checks happen]
- Validation: [where and how input is validated]
- Logging: [what's logged, what framework]

Naming Conventions:
- Files: [camelCase / kebab-case / PascalCase / snake_case]
- Functions: [pattern]
- Types: [prefix/suffix conventions]
- Database: [singular/plural, naming style]

Testing Patterns:
- Framework: [Jest/Vitest/Playwright/etc.]
- Style: [unit-heavy / integration-heavy / E2E-heavy]
- Mocking: [how external deps are mocked]
- Coverage: [approximate coverage level]
```

### Step 3: Dependency Map

Map how components depend on each other:

```
DEPENDENCY MAP:
═══════════════
[Component A]
  ├── depends on: [Component B, Component C]
  ├── depended on by: [Component D]
  └── external deps: [API X, Database Y]

[Component B]
  ├── depends on: [nothing]
  ├── depended on by: [Component A, Component E]
  └── external deps: [none]

Circular dependencies: [list any]
Highly coupled components: [list any with 5+ dependencies]
Isolated components: [list any with 0 dependents]
```

### Step 4: Critical Path Analysis

Identify the most important flows:

```
CRITICAL PATHS:
═══════════════
1. [Primary user flow — e.g., "User signs up"]
   Entry: [file:line] → [file:line] → [file:line] → Response
   Touches: [list of modules]
   Risk: [what could break this flow]

2. [Secondary flow — e.g., "User creates resource"]
   ...

3. [Background flow — e.g., "Cron job syncs data"]
   ...
```

### Step 5: Quirks & Gotchas

Document the non-obvious things that waste time:

```
QUIRKS & GOTCHAS:
═════════════════
- [Quirk]: [explanation + where it manifests]
  Example: "The auth middleware silently fails on expired tokens instead of
  returning 401 — it just sets req.user to null. Check auth/middleware.ts:45"

- [Technical debt]: [what it is + why it exists if apparent]
  Example: "Two separate user tables (users and legacy_users) because
  the migration from the old system was never completed"

- [Hidden dependency]: [something not obvious from the code]
  Example: "The PDF generator requires LibreOffice installed on the host —
  not documented anywhere, discovered from Dockerfile"
```

### Step 6: Health Assessment

Score the codebase health:

```
CODEBASE HEALTH:
════════════════
| Dimension | Score (1-10) | Notes |
|-----------|-------------|-------|
| Code Organization | [N] | [brief note] |
| Test Coverage | [N] | [brief note] |
| Documentation | [N] | [brief note] |
| Dependency Health | [N] | [brief note] |
| Error Handling | [N] | [brief note] |
| Security Posture | [N] | [brief note] |
| Build/Deploy | [N] | [brief note] |

Overall: [N]/70

Top 3 improvement areas:
1. [Area] — [specific action]
2. [Area] — [specific action]
3. [Area] — [specific action]
```

### Step 7: Persist the Insight

**This is the critical step.** Save the full analysis to a persistent file:

```
Output file: .codebase-insight.md (in project root)
```

The file should contain ALL of the above in a structured markdown document with a generation timestamp and a table of contents.

```markdown
# Codebase Insight — [Project Name]
> Generated: [YYYY-MM-DD HH:MM]
> Source: [commit hash at time of generation]

## Table of Contents
- [Project Overview](#project-overview)
- [Tech Stack](#tech-stack)
- [Architecture](#architecture)
- [Directory Map](#directory-map)
- [Patterns](#patterns)
- [Dependency Map](#dependency-map)
- [Critical Paths](#critical-paths)
- [Data Model](#data-model)
- [API Surface](#api-surface)
- [Quirks & Gotchas](#quirks--gotchas)
- [Health Assessment](#health-assessment)

[... full content ...]
```

### Step 8: Announce the File

After saving:

```
Codebase insight saved to .codebase-insight.md
[N] components mapped, [N] patterns identified, [N] critical paths traced.
Health score: [N]/70

This file will be available to future sessions for instant context loading.
To refresh: run /codebase-insight again.
```

## Insight Modes

### Quick Insight
Scan Steps 1-2 only. Produces a high-level overview without deep dependency or path analysis. Saves a shorter `.codebase-insight.md`.

### Standard Insight
All 8 steps. The default.

### Deep Insight
All 8 steps plus:
- Dispatch subagents to analyze different subsystems in parallel
- Include code quality metrics (function length distribution, cyclomatic complexity patterns)
- Map all environment variables and their usage
- Trace all external API integrations
- Analyze git history for hotspot files (most frequently changed)

### Delta Insight
When `.codebase-insight.md` already exists:
- Compare current codebase state to the saved insight
- Identify what's changed (new files, removed files, modified patterns)
- Update only the changed sections
- Append a changelog entry to the insight file

```markdown
## Insight Changelog
| Date | Changes |
|------|---------|
| [YYYY-MM-DD] | [what changed since last insight] |
```

## Multi-Project Support

In monorepos or multi-project directories:
- Ask which project to analyze (or do all)
- Save per-project: `.codebase-insight-[project-name].md`
- Include cross-project dependency map in each file

## Rules

- **Read before writing.** Scan the full codebase before producing any analysis.
- **Facts only.** Every claim must reference a specific file. No speculation.
- **Always persist.** The insight file is the product. Without it, the analysis evaporates.
- **Include the commit hash.** So future sessions know if the insight is stale.
- **Timestamp everything.** The insight file must show when it was generated.
- **Acknowledge gaps.** If parts of the codebase are unclear, say so. Don't fill gaps with guesses.
- **Keep it scannable.** Use tables and structured formats. Nobody reads walls of prose about architecture.