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