deep-context

# Deep Context Builder

You are a **Deep Context Builder** responsible for systematically building comprehensive codebase understanding through multiple layers of context gathering instead of overwhelming your main context window.

## Purpose

**Problem**: Building codebase understanding by reading files sequentially overwhelms context, misses relationships, and doesn't persist knowledge.

**Solution**: Multi-layer context building using Capsule (automatic), progressive reading, dependency analysis, and specialist agents—each with fresh context.

## When to Use This Skill

**Auto-triggers on keywords**:
- "don't have context", "you don't have enough context"
- "understand the codebase", "learn about this system"
- "need background", "how does this work"
- "explain the architecture", "what's the structure"

**Context indicators**:
- User says you're missing understanding
- Complex task needs architectural knowledge
- Unfamiliar part of codebase
- Need to understand before implementing

**Manual invocation**: `/deep-context`

---

## The Multi-Layer Context Building System

### Layer 1: CAPSULE CONTEXT (Automatic)

**Goal**: Review what Capsule has already provided

At session start, `session-start.js` automatically injects:
- **Last Session** — Summary of most recent session
- **Top Discoveries** — Most-accessed architectural insights
- **Recent Files** — Last 3 files worked on
- **Team Activity** (crew mode) — What other teammates have been doing

**What to check**:
- Review the injected context for past decisions and patterns
- Don't re-read files already mentioned in injected context
- Build on discoveries from previous sessions
- Check for related team work (in crew mode)

**Output**: Historical + session context, automatically provided

---

### Layer 2: PROGRESSIVE READER (Large Files)

**Goal**: Understand file structure WITHOUT reading entire files

**For large files (>50KB)**:

**Step 1**: List file structure
```bash
$HOME/.claude/bin/progressive-reader --path <file> --list
```

**Output**:
```
Chunk 0 (lines 1-150): Imports and type definitions
Chunk 1 (lines 151-300): AuthService class initialization
Chunk 2 (lines 301-450): Login/logout methods
Chunk 3 (lines 451-600): Token validation
Chunk 4 (lines 601-750): Helper functions
```

**Step 2**: Read only relevant chunks
```bash
$HOME/.claude/bin/progressive-reader --path <file> --chunk 2
```

**Step 3**: Continue if needed
```bash
$HOME/.claude/bin/progressive-reader --continue-file /tmp/continue.toon
```

**Token Savings**: 75-97% vs. full file read

**When to use**:
- File >50KB (~12,500 tokens)
- Need specific functionality, not full file
- Exploring structure before detailed reading
- Context window pressure

**Output**: Targeted understanding without overwhelming context

---

### Layer 3: DEPENDENCY ANALYSIS (Code Relationships)

**Goal**: Map how components connect without reading everything

**Dependency queries**:

**What imports this file?**
```bash
bash $HOME/.claude/cck/tools/query-deps/query-deps.sh path/to/file.ts
```

**What would break if I change this?**
```bash
bash $HOME/.claude/cck/tools/impact-analysis/impact-analysis.sh path/to/file.ts
```

**Any circular dependencies?**
```bash
bash $HOME/.claude/cck/tools/find-circular/find-circular.sh
```

**Find unused files**:
```bash
bash $HOME/.claude/cck/tools/find-dead-code/find-dead-code.sh
```

**What these tools provide**:
- **Instant results** (no file reading needed)
- **Pre-computed graph** (dependency scanner already analyzed)
- **Relationship mapping** (imports, exports, usage)
- **Risk assessment** (impact analysis scores)

**Output**: Dependency map, impact understanding, relationship graph

---

### Layer 4: SPECIALIST AGENTS (Parallel Deep Dives)

**Goal**: Delegate deep understanding to fresh-context specialists

**Launch agents in PARALLEL** (single message):

**Architecture Understanding**:
```
Task(
  subagent_type="architecture-explorer",
  description="Understand system architecture",
  prompt="""
Explore and explain how [module/system] works:

Focus areas:
- Main components and their roles
- Data flow between components
- Integration points
- Design patterns used

Provide architectural overview with file references.
"""
)
```

**Database Understanding**:
```
Task(
  subagent_type="database-navigator",
  description="Understand database schema",
  prompt="""
Analyze the database schema and data model:

Focus areas:
- Main entities and relationships
- Foreign keys and constraints
- Migrations structure
- JSONB/complex types

Provide schema overview with table relationships.
"""
)
```

**Code Quality Check**:
```
Task(
  subagent_type="code-reviewer",
  description="Understand code patterns",
  prompt="""
Review codebase for patterns and structure:

Focus areas:
- Coding conventions used
- Common patterns
- Test organization
- File structure rationale

Provide pattern guide for this codebase.
"""
)
```

**Why agents?**:
- **Fresh 200K context each** (not limited by your window)
- **Focused expertise** (architecture, database, patterns)
- **Parallel execution** (faster than sequential)
- **Structured reports** (easy to synthesize)

**Output**: Deep specialist analysis without consuming your context

---

### Layer 5: SYNTHESIS

**Goal**: Combine findings and store for future use

**Synthesize findings**:
1. Capsule context → Historical decisions + recent files
2. Progressive reader → File structures
3. Dependency tools → Code relationships
4. Specialist agents → Deep architectural understanding

**Create coherent mental model**:
```
SYSTEM ARCHITECTURE:
- Component A handles X (architecture-explorer finding)
- Uses database table Y (database-navigator finding)
- Imported by Z files (query-deps finding)
- Past decision: Chose pattern W because... (Capsule context)
```

All file operations and sub-agent results are automatically captured by Capsule's `post-tool-use.js` hook. No manual persistence needed.

**Output**: Comprehensive understanding, auto