irfad7 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.
# 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
## 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.