Codebase Knowledge Builder

Codebase Knowledge Builder

Transform from a generalist into a codebase specialist by systematically studying a repository and producing high-quality knowledge artifacts. The process follows a strict "read first, write later" principle across four sequential phases.

Prerequisites

• File read access to the target repository (cloned locally or accessible via tools)
• Bash access for file counting and structure discovery
• Write access to produce scratch files and final artifacts

Workflow

1. Reconnaissance -- Build a broad mental model of the entire repo 2. Deep-Dive Study -- Investigate each requested topic in isolation 3. Artifact Authoring -- Synthesize findings into polished knowledge artifacts 4. Delivery -- Package and deliver artifacts to the user

---

Phase 1: Reconnaissance

Clone the repo and build a high-level map before touching any specific topic.

1. Run find . -type f -name '*.js' -o -name '*.ts' -o -name '*.py' | head -50 and wc -l to gauge scale. 2. Read the main entry point file end-to-end. 3. Follow the checklist in references/recon-checklist.md to systematically discover architecture, entry points, config systems, and key abstractions. 4. Save a structured summary to a scratch file (recon_findings.md) with: tech stack, directory map, module responsibilities, design patterns, and open questions.

Do not proceed to Phase 2 until the repo's architecture can be described in one paragraph.

Phase 2: Deep-Dive Study

For each topic the user requests, perform a focused investigation. Study each topic separately -- do not mix concerns.

1. Read references/deep-dive-methodology.md for file reading strategies, tracing patterns, and note-taking protocol. 2. Start from the subsystem's entry point and follow imports outward (dependency order, not alphabetical). 3. Trace three paths per subsystem: happy path, error path, edge cases. 4. After every 2-3 files, save key findings to a scratch file. Do not rely on context memory alone. 5. For each file, capture: purpose (one sentence), key functions, what it calls, what calls it, and gotchas.

Phase 3: Artifact Authoring

Synthesize each topic's findings into a standalone knowledge artifact.

1. Copy the template from templates/knowledge_artifact.md for each topic. 2. Fill every section -- Overview, Architecture, Key Components table, Data & Control Flow, Key Functions table, Configuration table, Gotchas, Extension Points, and Visual Flow diagram. 3. Include Mermaid diagrams: use sequenceDiagram for flows, graph TD for architecture. 4. Each artifact must be self-contained -- a developer reading only that artifact should understand the subsystem completely.

Phase 4: Delivery

Attach all completed Markdown artifacts to a message to the user. Include a brief summary of what each artifact covers.

---

Limitations

• Large monorepos (>10,000 files) may require scoping to specific directories or packages before starting reconnaissance.
• Binary files, compiled assets, and vendored dependencies should be excluded from study.
• Knowledge artifacts reflect the codebase at a point in time. Major refactors may invalidate sections.

Quality Checklist

Before delivering any artifact, verify:

Bundled Resources

Deep-Dive Methodology

Table of Contents

1. File Reading Strategy 2. Tracing Patterns 3. Note-Taking Protocol 4. Common Subsystem Types

1. File Reading Strategy

Read files in dependency order, not alphabetical order. Start from the entry point of the subsystem being studied and follow imports outward. For each file:

1. Read the module-level docstring or header comment first -- it often explains the "why." 2. Identify the exported functions/classes -- these are the public API. 3. Read the constructor or initialization logic -- this reveals dependencies. 4. Read the primary execution method -- this is the core logic. 5. Scan for error handling, edge cases, and commented-out code -- these reveal history.

When a file is too long (>500 lines), use range-based reading. Start with lines 1-100 to get the imports and class definition, then jump to the method needed.

2. Tracing Patterns

For each subsystem, trace these three paths:

Happy Path: The normal, successful execution flow from trigger to completion. This is the backbone of the artifact.

Error Path: What happens when things go wrong. Look for try/catch blocks, error classes, fallback logic, and retry mechanisms.

Edge Cases: Caching behavior, race conditions, concurrent access, timeout handling. These are the gotchas that make the difference between a junior and a senior developer.

3. Note-Taking Protocol

After every 2-3 files read, save key findings to a scratch file. Do not rely on context window memory alone. Structure notes as:

## [File Path]
- Purpose: [one sentence]
- Key functions: [list]
- Calls: [what it calls]
- Called by: [what calls it]
- Gotchas: [non-obvious behavior]

4. Common Subsystem Types

Different subsystem types require different investigation angles:

Codebase Reconnaissance Checklist

Use this checklist during Phase 1 (Reconnaissance) to build a complete mental model of the codebase before diving into specific topics.

Repository Structure

• [ ] Clone the repo and list top-level directories
• [ ] Count total source files by extension (find . -type f -name '*.js' | wc -l)
• [ ] Identify the primary language and framework
• [ ] Locate the main entry point (e.g., index.js, main.py, app.ts)
• [ ] Map the directory tree to understand module boundaries

Architecture Discovery

• [ ] Read the entry point file end-to-end
• [ ] Identify the service/module initialization order
• [ ] Map imports to understand dependency graph between core modules
• [ ] Identify the configuration system (env vars, config files, Redis, etc.)
• [ ] Locate the routing layer (HTTP routes, socket handlers, CLI commands)

Key Abstractions

• [ ] Identify base classes, interfaces, or abstract patterns
• [ ] Locate factory or builder patterns
• [ ] Find middleware chains and their ordering
• [ ] Identify the plugin/extension mechanism (if any)

Data Flow

• [ ] Trace a request from entry to response (happy path)
• [ ] Identify the state management approach (in-memory, Redis, DB)
• [ ] Locate caching layers and their invalidation strategy
• [ ] Find the serialization/deserialization boundaries

Save Findings

After completing reconnaissance, save a structured summary to findings.md with:

• Tech stack and framework versions
• Directory structure overview
• Core module map (module -> responsibility)
• Key design patterns identified
• Questions or ambiguities to resolve during deep-dive phases

[REPO_NAME]: [TOPIC_TITLE]

<!-- Knowledge Artifact Template Fill each section with codebase-specific detail. Remove this comment block before delivery. -->

1. Overview

[One paragraph explaining what this subsystem does, why it exists, and how it fits into the broader architecture.]

2. Architecture

[Describe the high-level architecture of this subsystem. Explain the key design decisions and patterns used.]

3. Key Components

4. Data & Control Flow

[Walk through the end-to-end flow step by step, from trigger to completion. Number each step.]

1. [Step 1] 2. [Step 2] 3. ...

5. Key Functions & Methods

6. Configuration & Environment

7. Gotchas, Pitfalls & Critical Fixes

[Document non-obvious behaviors, historical bugs that were fixed (and why), race conditions, caching quirks, or anything that would trip up a developer who hasn't read the git history.]

8. Extension Points

[Where and how a developer would add new functionality to this subsystem. Be specific about files, patterns, and conventions to follow.]

9. Visual Flow

[Include a Mermaid diagram -- sequenceDiagram for flows, graph TD for architecture]