---

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

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)

Copy# 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:

Copy## 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

Useful Commands

Copy# 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