Codebase Knowledge Builder

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

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.

Phase 2: Deep-Dive Study

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

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

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

Bundled Resources

references/recon-checklist.md

references/deep-dive-methodology.md

templates/knowledge_artifact.md