Deep Read — Codebase Reading Engine

Systematic source-code-first analysis protocol. Reads implementations, not just interfaces. Every finding cites file:line .

Core principle: Source code is the source of truth. Documentation lies, comments rot, function names mislead. Read the actual code.

Protocol

Process every /deep-read invocation through these 6 phases in strict order. Never skip a phase. Gate each phase: do not advance until the gate condition is met.

Phase 1: SCOPE — Define the Reading Target

Narrow the target to a tractable area before reading anything.

• Parse $ARGUMENTS as the reading target (module, flow, question, or path)

• Read CLAUDE.md and MEMORY.md for project context — but treat these as hints, not truth

• Run initial discovery to estimate scope:

• Glob for relevant file patterns (**/.ts , **/.py , etc.)

• Grep for key terms from the target description

• Count matching files

• If scope exceeds 50 source files:

• Use AskUserQuestion to narrow: which subsystem, which flow, which layer?

• Suggest specific narrowing options based on directory structure

• If the target is a question (e.g., "how are commissions calculated?"):

• Translate to concrete search terms

• Grep for domain terms to locate relevant modules

• If the target is a path (e.g., src/services/billing/ ):

• List all files in the path

• Identify entry points (exported functions, route handlers, main files)

Output: A scope definition listing:

• Target description (1-2 sentences)

• File list (< 50 source files)

• Identified entry points

• Out-of-scope areas (explicitly noted)

Gate: Scope is defined and contains < 50 source files. Entry points identified. Proceed.

Phase 2: MAP — Build Structural Overview

Understand the shape of the code before reading it deeply.

• Directory structure — map the relevant directories:

• Use Glob to list files by type and directory

• Note the organizational pattern (by feature, by layer, by domain)

• Tech stack — identify from configs (not from docs):

• Read package.json , Cargo.toml , go.mod , requirements.txt , or equivalent

• Note frameworks, key dependencies, build tools

• Entry points — verify by reading actual files (not just file names):

• Read route definitions, main files, exported modules

• Read the first 50 lines of each candidate entry point

• Confirm which files are actual entry points vs. helpers

• Dependency graph — map internal imports within the scope:

• Grep for import/require statements within scoped files

• Build a mental model: what calls what, what depends on what

• Identify the core files (most imported by others)

• Configuration and constants — read files that define behavior:

• Config files, environment schemas, constants, enums, types

• These shape behavior as much as code does

Launch parallel Explore agents for steps 2-4 if the scope has 20+ files.

Output: Structural map including:

• Directory layout with annotations

• Tech stack (from configs, not docs)

• Entry points (verified by reading)

• Dependency flow diagram (text-based)

• Core files ranked by centrality

Gate: Entry points verified by reading actual files. Dependency flow mapped. Proceed.

Phase 3: TRACE — Follow Execution Paths

Start from entry points and trace through the code. Read every file in the path.

• Select the primary execution path based on the reading target:

• For a flow (e.g., "payment processing"): start at the user-facing entry point

• For a module: start at its public API / exports

• For a question: start at the code most likely to contain the answer

• Trace forward from the entry point:

• Read the entry point file in full with the Read tool

• For every function call, class instantiation, or module import encountered:

• Grep to locate the implementation (not just the type signature)

• Read the implementation file in full

• Continue until reaching terminal operations (DB queries, API calls, file I/O, return values)

• Document the path as a chain with file:line citations: Request enters at routes/payments.ts:42 (POST /api/payments) -> calls PaymentService.processPayment() at services/payment.ts:87 -> validates input via PaymentSchema at schemas/payment.ts:15 -> calls StripeClient.charge() at clients/stripe.ts:34 -> constructs request at clients/stripe.ts:45-62 -> stores result via PaymentRepository.save() at repos/payment.ts:28 -> returns PaymentResponse at routes/payments.ts:58

• Trace secondary paths if the reading target involves multiple flows:

• Error paths, edge cases, fallback logic

• Event handlers, webhooks, background jobs triggered by the primary path

• Note every branch point — conditions, switches, feature flags:

• What determines which path is taken?

• Read the condition logic, don't just note "there's a conditional here"

Output: Complete execution trace(s) with file:line citations for every step.

Gate: At least 1 complete path traced from entry to terminal. Every file in the path has been Read in full. Proceed.

Phase 4: DEEP READ — Line-by-Line Analysis of Critical Files

This is the core phase. Read critical files thoroughly, understanding every line of business logic.

• Identify critical files from Phase 3 — files that contain:

• Business logic (calculations, rules, transformations)

• State management (mutations, transactions, side effects)

• Security logic (auth, validation, access control)

• Data transformations (mapping, filtering, aggregation)

• Error handling (catch blocks, error boundaries, recovery logic)

• Read each critical file in full with the Read tool:

• Do NOT skim — read the entire file

• For files > 500 lines: read in sections, but read ALL sections

• Launch parallel Read calls for independent files

• For each critical file, document:

• Purpose: What this file actually does (based on code, not comments)

• Key functions: Each function's logic, with citations: calculateCommission(sale: Sale): number [billing/commission.ts:45-78]

  • Base rate: 5% of sale.amount (line 52)
  • Bonus tier: if sale.amount > 10000, rate += 2% (line 56)
  • Cap: commission capped at 5000 (line 62)
  • Proration: multiplied by daysInPeriod/30 (line 67)
  • Returns: rounded to 2 decimal places (line 74)

• Formulas and conditions: Write out the actual math and logic, not summaries

• State changes: What gets mutated, what side effects occur

• Edge cases handled: Null checks, bounds, error recovery

• Edge cases NOT handled: Missing validation, unchecked assumptions

• Cross-reference between files:

• When file A calls file B, verify that A's expectations match B's implementation

• Note any mismatches between interface contracts and implementations

• Check that error handling in callers matches errors thrown by callees

Output: Detailed analysis of each critical file with:

• Function-level logic documentation with file:line citations

• Formulas written out explicitly

• Conditions and branch logic documented

• State changes and side effects listed

Gate: Every critical file (identified in step 1) has been Read in full. Logic documented with formulas, conditions, and citations. Proceed.

Phase 5: CONNECT — Synthesize Understanding

Step back and reason about the system as a whole. Use sequential-thinking MCP for structured analysis.

• Start a sequential-thinking chain with all evidence from Phases 1-4: mcp__sequential-thinking__sequentialthinking({ thought: "Synthesizing understanding of <target>. Evidence from phases: ...", thoughtNumber: 1, totalThoughts: 8, nextThoughtNeeded: true })

• Identify patterns across the codebase (minimum 3):

• Architectural patterns (layering, dependency injection, event-driven, etc.)

• Coding conventions (error handling style, naming patterns, data flow patterns)

• Implicit rules (invariants maintained by convention, not enforced by code)

• Anti-patterns or technical debt

• Map data flows end to end:

• How does data enter the system?

• What transformations does it undergo? (with file:line citations)

• Where does it end up? (DB, API response, file, event)

• Identify risks and assumptions:

• What assumptions does the code make that aren't validated?

• What would break if those assumptions were violated?

• Are there race conditions, consistency gaps, or security concerns?

• Answer the original question if the reading target was a question:

• Provide the answer with full evidence chain

• Cite every source

Use branching in sequential-thinking to explore alternative interpretations of ambiguous code.

Output: Synthesis including:

• 3+ patterns identified with evidence (file:line )

• End-to-end data flow map

• Risk assessment

• Answer to the original question (if applicable)

Gate: At least 5 reasoning steps completed. At least 3 patterns identified with file:line evidence. Proceed.

Phase 6: REPORT — Structured Deliverable

Produce the final report. Every claim must cite file:line .

Deep Read Report: <target>

Scope

• Target: <what was analyzed>
• Files analyzed: <count> files, <count> read in full
• Entry points: <list with file:line>

Architecture Overview

<structural summary from Phase 2 — directory layout, tech stack, dependency flow>

Execution Flow

<traced paths from Phase 3 — entry to terminal with file:line citations>

Critical Logic

<detailed function-level analysis from Phase 4>

For each critical area:

• What it does: <plain language description>
• How it works: <formulas, conditions, logic with file:line>
• State changes: <what gets mutated>
• Edge cases: <handled and unhandled>

Patterns & Conventions

<synthesized patterns from Phase 5>

1. <pattern> — evidence: <file:line>
2. <pattern> — evidence: <file:line>
3. <pattern> — evidence: <file:line>

Data Flow

<end-to-end data flow map from Phase 5>

Risks & Assumptions

<risk assessment from Phase 5>

Key Findings

<concise bullet list of the most important discoveries>

• <finding> — <file:line>

Answer

<if the reading target was a question, answer it here with full evidence>

Gate: All sections populated. Every finding cites file:line . Report complete.

Tool Usage by Phase

Phase Primary Tools When to Use Agents

1. SCOPE Read, Glob, Grep, AskUserQuestion --

2. MAP Glob, Grep, Read (configs, entry points) Explore agents (parallel) for 20+ file codebases

3. TRACE Read (full files), Grep (cross-refs) Explore agent for locating implementations

4. DEEP READ Read (full files, parallel) --

5. CONNECT sequential-thinking MCP deep-analysis skill for complex reasoning

6. REPORT Structured output --

Anti-Patterns — What This Skill Prevents

Bad Habit What /deep-read Does Instead

Read README/CLAUDE.md and call it done Phase 1 treats docs as hints; Phases 3-4 read source

Skim file headers and imports only Phase 4 requires line-by-line reading with citations

Summarize without evidence Every claim must cite file:line

Stop at the first abstraction layer Phase 3 traces full call chains to leaf functions

Rely on function names to infer behavior Phase 4 reads implementations, documents actual logic

Produce vague "this seems to do X" Phase 4 requires concrete formulas and conditions

Read types/interfaces instead of implementations Phase 3 Greps for implementations, not just signatures

Skip error paths and edge cases Phase 3 traces secondary paths; Phase 4 documents edge cases

Scope Examples

/deep-read payment processing flow from checkout to settlement /deep-read src/services/billing/ /deep-read how are sales commissions calculated and distributed? /deep-read the authentication and authorization system /deep-read data pipeline from ingestion to reporting dashboard /deep-read how does the caching layer work and when does it invalidate?

When to Use /deep-read vs Other Tools

Situation Use

Understand how existing code works /deep-read

Quick "what does this function do?" Read tool directly

Bug, crash, error, unexpected behavior /investigate

Architecture decision or trade-off /deep-analysis

Build a new feature /execute

Understand code, then reason about it /deep-read then /deep-analysis

Understand code, then redesign it /deep-read then /deep-analysis then /execute

Onboard to an unfamiliar codebase /deep-read

Code review with full context /deep-read then code-quality agent

References

See references/reading-strategies.md for codebase-type-specific reading strategies and context management approaches.