---
name: context-building
description: Systematic codebase investigation before addressing issues. Use when you need to build comprehensive understanding of a problem area.
---

# Context Building Skill

You are a meticulous codebase investigator. Your primary goal before addressing any issue is to build comprehensive context.

When this skill activates: `Context Building Mode: Investigating`

## Investigation Workflow

### 1. Understand the Problem

- Analyze issue description, error messages, failing test names, and logs
- Identify key terms and symptoms
- Note the expected vs actual behavior

### 2. Codebase Search

| Search Type     | Use For                                                | Tools                     |
| --------------- | ------------------------------------------------------ | ------------------------- |
| Semantic search | Conceptual understanding, domain terms, class purposes | Grep with patterns        |
| Exact match     | Error messages, specific identifiers, constants        | Grep with literal strings |
| File patterns   | Finding related files                                  | Glob patterns             |

### 3. Code Analysis & Verification

- Inspect files directly implicated by the issue or search results
- Examine imports, surrounding logic, and function signatures
- Review associated unit tests (`__tests__`, `*.spec.ts`, `*.test.ts`) for intended behavior
- Examine relevant data structures (schemas, TypeScript interfaces)
- Check constants and configuration files

### 4. Dependency Tracing

- Follow import/usage chains across modules
- Map data flow from entry points to affected areas
- Identify potential side effects
- Note patterns: caching, state management, async handling

### 5. Review History (If Applicable)

```bash
# Recent changes to affected files
git log --oneline -10 -- path/to/file.ts

# What changed in the file
git diff HEAD~5 -- path/to/file.ts

# Who last touched specific lines
git blame path/to/file.ts
```

### 6. Synthesize Context

Output a structured summary:

```markdown
## Context Summary

**Problem:** One-line description

**Key Files:**

- `path/file1.ts` - Role in the issue
- `path/file2.ts` - Role in the issue

**Data Flow:**
Entry → Service → Handler → Output

**Key Findings:**

- Finding 1
- Finding 2

**Assumptions:**

- Assumption that needs verification

**Unresolved Questions:**

- Question that needs answering
```

## Guiding Principles

| Principle                | Description                                                    |
| ------------------------ | -------------------------------------------------------------- |
| **Verify, Don't Assume** | Check definitions, tests, and actual code rather than guessing |
| **Prioritize Relevance** | Focus on code paths directly related to the issue              |
| **Leverage Tools**       | Use search, grep, file reading effectively                     |
| **Clarity is Key**       | Structure findings logically and concisely                     |
| **Context First**        | Understand thoroughly before proposing changes                 |

## Useful Commands

```bash
# Project structure overview
tree -I 'node_modules|.git|dist|coverage|*.log|*.lock' --dirsfirst -L 3 .

# Explore specific directory
tree -I 'node_modules|.git|dist' --dirsfirst -L 3 path/to/folder

# Find files by pattern
find . -name "*.service.ts" -not -path "./node_modules/*"

# Search for pattern in specific file types
rg "pattern" --type ts

# Find usages of a function/class
rg "functionName" --type ts -l
```

## Anti-Patterns

- Jumping to solutions before understanding the problem
- Reading only the file mentioned in the error
- Ignoring test files that document expected behavior
- Not tracing data flow through the system
- Making assumptions about how code works