2649 Research Strategies 38402a34

Research Strategies for Context Gathering

This reference provides systematic approaches for researching codebase context, best practices, and patterns before formulating clarifying questions.

Table of Contents

• Research Planning Framework
• Codebase Exploration Strategies
• Documentation Research
• Web Research for Best Practices
• Conversation History Mining
• Tool Selection Guide
• Research Execution Patterns

Research Planning Framework

Phase 1: Identify What's Unclear

Before researching, explicitly identify gaps:

Target Gap:

• "Which file/function needs modification?"
• "What component is involved?"

Approach Gap:

• "How should this be implemented?"
• "What pattern should be used?"

Scope Gap:

• "How much should be changed?"
• "What's included in this request?"

Context Gap:

• "What's the current state?"
• "What patterns exist already?"

Phase 2: Create Research Plan with TodoWrite

Use TodoWrite to create a research plan before executing. This ensures systematic investigation.

Template:

Research Plan for [Prompt Type]:
1. [What to research] - [Tool/approach]
2. [What to research] - [Tool/approach]
3. [What to research] - [Tool/approach]

Example:

Research Plan for "fix the bug":
1. Check conversation history for error messages - Review recent messages
2. Search for failing tests - Grep for "failing", "error", "TODO"
3. Explore recent commits - Git log for problem areas
4. Identify patterns in similar code - Read related files

Phase 3: Execute Research

Systematically execute each research step, documenting findings.

Phase 4: Document Findings

Summarize what you learned:

• Key files involved
• Existing patterns found
• Common approaches in the codebase
• Relevant best practices
• Constraints or requirements discovered

Codebase Exploration Strategies

Strategy 1: Pattern Discovery (Task/Explore Agent)

When to use: Need to understand architecture, find similar implementations, or explore unknown territory

Approach:

Use Task tool with subagent_type=Explore to:
- Map codebase structure
- Find similar implementations
- Understand architectural patterns
- Identify relevant components

Example:

Prompt: "find the bug"

Research:
1. Launch Explore agent: "Find error handling patterns in authentication code"
2. Results: Discover auth.ts, middleware.ts, session.ts with different error patterns
3. Finding: Inconsistent error handling across auth files

Strategy 2: Targeted File Search (Glob)

When to use: Know what you're looking for (file type, name pattern)

Common patterns:

# Find all authentication-related files
**/*auth*.ts

# Find test files
**/*.test.ts
**/*.spec.ts

# Find configuration files
**/*config*.{json,yaml,yml}
**/.*rc

# Find documentation
**/*.md
**/README*

Example:

Prompt: "add tests"

Research:
1. Glob: "**/*.test.ts" → Find existing test files
2. Identify pattern: Tests colocated with source files
3. Finding: Use Jest, tests in __tests__/ directories

Strategy 3: Content Search (Grep)

When to use: Looking for specific code patterns, function calls, or keywords

Effective searches:

# Find authentication implementations
pattern: "authenticate|login|auth"

# Find TODOs and FIXMEs
pattern: "TODO|FIXME|XXX|HACK"

# Find error handling
pattern: "try.*catch|throw new|Error\\("

# Find specific function calls
pattern: "validateUser\\(|checkAuth\\("

# Find configuration usage
pattern: "process\.env|config\.|getConfig"

Example:

Prompt: "improve error handling"

Research:
1. Grep: "try.*catch" with multiline mode
2. Grep: "throw new Error"
3. Finding: 15 try/catch blocks, 8 throw different error types
4. Pattern: Some use custom errors (AuthError, ValidationError), some use generic Error

Strategy 4: Architecture Understanding (Read + Explore)

When to use: Need to understand how systems connect

Approach:

1. Start with entry points (index.ts, main.ts, app.ts)
2. Read key configuration files (package.json, tsconfig.json)
3. Explore directory structure
4. Read README.md and architecture docs

Example:

Prompt: "refactor the API"

Research:
1. Read: package.json → Express.js backend
2. Read: src/index.ts → Entry point, middleware setup
3. Explore: src/routes/ → Route organization pattern
4. Finding: RESTful API with route/controller/service layers

Strategy 5: Historical Context (Git Commands)

When to use: Understanding evolution, finding related changes

Useful git commands via Bash:

# Recent commits
git log --oneline -20

# Commits affecting specific file
git log --oneline path/to/file

# Search commit messages
git log --grep="authentication" --oneline

# Find when function was added
git log -S "functionName" --oneline

# See recent changes
git diff HEAD~5..HEAD --stat

Example:

Prompt: "fix the recent regression"

Research:
1. Git log: Last 10 commits
2. Git log --grep="fix|bug": Recent bug fixes
3. Finding: Commit 3 days ago changed auth flow
4. Pattern: Regression likely in authentication changes

Documentation Research

Strategy 1: Local Documentation (Read)

Priority order:

1. README.md at project root
2. docs/ directory
3. Package-specific READMEs (packages/*/README.md)
4. CONTRIBUTING.md
5. Architecture docs (.architecture/, docs/architecture/)
6. API documentation (docs/api/)

Example:

Prompt: "implement caching"

Research:
1. Read: README.md → Check if caching mentioned
2. Read: docs/architecture.md → Current caching strategy?
3. Finding: Redis already used for session caching
4. Pattern: Use Redis for new caching needs (consistency)

Strategy 2: Package Documentation (Read + WebFetch)

When to use: Understanding third-party library usage

Approach:

1. Read package.json for library versions
2. Check local docs or examples
3. WebFetch official documentation if needed

Example:

Prompt: "update the validation"

Research:
1. Read: package.json → Using Joi@17.6.0
2. Grep: "Joi\." → Find current usage patterns
3. WebFetch: "https://joi.dev/api/" → Current best practices
4. Finding: Using outdated Joi patterns, v17 has simpler syntax

Strategy 3: Code Comments (Grep)

When to use: Finding design decisions, warnings, constraints

Patterns:

# Find important comments
pattern: "NOTE:|WARNING:|IMPORTANT:|FIXME:"

# Find documentation comments
pattern: "/\\*\\*|@param|@returns"

# Find constraint notes
pattern: "must|require|cannot|constraint"

Example:

Prompt: "modify the database schema"

Research:
1. Grep: "NOTE:|WARNING:" in migrations/
2. Finding: "NOTE: Cannot modify user_id - foreign keys depend on it"
3. Constraint: Must preserve user_id column

Web Research for Best Practices

Strategy 1: Current Best Practices (WebSearch)

When to use: Need current approaches, recent changes, industry standards

Effective queries:

# Framework-specific patterns
"React authentication best practices 2024"
"Express.js error handling patterns 2024"

# Library comparisons
"JWT vs session authentication comparison"
"Joi vs Zod validation library comparison"

# Implementation approaches
"implement rate limiting Node.js"
"database transaction patterns TypeScript"

# Common problems
"fix N+1 query problem TypeScript"
"prevent SQL injection Node.js"

Example:

Prompt: "add authentication"

Research:
1. WebSearch: "Node.js authentication best practices 2024"
2. Finding: Passport.js is mature, NextAuth.js is newer, JWT is standard
3. WebSearch: "JWT vs session authentication comparison"
4. Finding: JWT for stateless, sessions for simplicity
5. Pattern: Choose based on project architecture (microservices → JWT)

Strategy 2: Framework Documentation (WebFetch)

When to use: Need official guidance for frameworks in use

Common documentation sites:

# JavaScript/TypeScript
https://developer.mozilla.org/docs/
https://nodejs.org/docs/
https://www.typescriptlang.org/docs/

# Frameworks
https://reactjs.org/docs/
https://expressjs.com/
https://nextjs.org/docs/

# Tools
https://jestjs.io/docs/
https://prettier.io/docs/

Example:

Prompt: "update the middleware"

Research:
1. Read: package.json → Express.js 4.18.2
2. WebFetch: "https://expressjs.com/en/guide/using-middleware.html"
3. Finding: Express 4.x supports async middleware
4. Pattern: Can use async/await instead of callbacks

Strategy 3: Common Architectures (WebSearch + WebFetch)

When to use: Implementing well-known patterns

Queries:

"repository pattern TypeScript example"
"MVC architecture Node.js best practices"
"clean architecture Node.js implementation"
"microservices patterns"

Example:

Prompt: "refactor data access"

Research:
1. WebSearch: "repository pattern TypeScript"
2. Finding: Separate data access from business logic
3. WebSearch: "repository pattern with dependency injection"
4. Finding: Use interfaces for testability
5. Pattern: UserRepository interface + implementation

Conversation History Mining

Strategy 1: Recent Context Review

When to use: Always (first step in research)

Check for:

• Error messages in recent messages
• File names mentioned
• Features discussed
• Decisions made
• Code shown or referenced

Example:

Recent messages:
User: "I'm getting TypeError: Cannot read property 'id' of undefined"
User: "It happens when I click the login button"
User: "fix it"

Research:
1. Error from history: undefined property access
2. Context: Login button click event
3. Implied target: Login button handler
4. Decision: Clear from context, no additional research needed

Strategy 2: Topic Tracking

When to use: Understanding what user is working on

Pattern:

• Last 5-10 messages establish working context
• File views indicate focus area
• Previous questions show user intent

Example:

Message history:
5 messages ago: "How do I implement caching in Express?"
3 messages ago: "Should I use Redis or in-memory cache?"
1 message ago: "ok let's use Redis"
Current: "implement it"

Research:
1. Topic: Caching implementation with Redis
2. Decision made: Use Redis (not in-memory)
3. Context: Express.js project
4. Clear: Implement Redis caching in Express

Strategy 3: File View Context

When to use: User viewing specific file

System messages indicate:

[System: User opened src/api/auth.ts]

Example:

[System: User opened src/components/LoginForm.tsx]
User: "refactor this to use hooks"

Research:
1. File context: LoginForm.tsx (React component)
2. User viewing: Specific component
3. Request: Convert to hooks
4. Clear: Refactor LoginForm.tsx from class to hooks

Tool Selection Guide

Choosing the Right Tool

Task/Explore Agent:

• Broad exploration needed
• Understanding architecture
• Finding similar patterns
• Complex multi-step research

Glob:

• Finding files by name pattern
• Known file types
• Specific naming conventions

Grep:

• Searching code content
• Finding function calls
• Pattern matching
• TODO/FIXME discovery

Read:

• Reading specific files
• Documentation review
• Configuration inspection
• Package.json analysis

Bash (git commands):

• Historical context
• Recent changes
• Commit messages
• File history

WebSearch:

• Current best practices
• Industry standards
• Library comparisons
• Common solutions

WebFetch:

• Official documentation
• Specific documentation pages
• API references
• Tutorial content

Multi-Tool Research Patterns

Pattern 1: Architecture Discovery

1. Read: package.json (understand stack)
2. Read: README.md (understand project)
3. Task/Explore: Map architecture
4. Glob: Find similar files
5. Read: Representative files

Pattern 2: Implementation Approach

1. Grep: Search for existing pattern
2. Read: Example implementation
3. WebSearch: Best practices
4. WebFetch: Official docs
5. Synthesize: Combine findings

Pattern 3: Bug Investigation

1. Review: Conversation history for errors
2. Grep: Search for error patterns
3. Bash: Git log for recent changes
4. Read: Affected files
5. Task/Explore: Find related code

Research Execution Patterns

Pattern 1: Quick Research (1-2 tools)

When: Simple ambiguity, limited scope

Example:

Prompt: "add tests"

Research:
1. Glob: "**/*.test.ts" → Find test pattern
2. Read: "src/__tests__/example.test.ts" → See structure

Findings:
- Jest framework
- Tests in __tests__/ directories
- Pattern established

Pattern 2: Moderate Research (3-4 tools)

When: Multiple unknowns, need pattern understanding

Example:

Prompt: "improve error handling"

Research:
1. Grep: "try.*catch|throw new Error" → Find current patterns
2. Read: Key files with error handling
3. WebSearch: "Node.js error handling best practices 2024"
4. Task/Explore: Map error flow through app

Findings:
- Inconsistent error types
- Some use custom errors, some generic
- Best practice: Centralized error handler
- Pattern: Implement custom error classes

Pattern 3: Comprehensive Research (5+ tools)

When: Major feature, architectural decision, complex implementation

Example:

Prompt: "add authentication"

Research:
1. Read: package.json → Current dependencies
2. Task/Explore: Map current auth (if any)
3. Grep: "auth|login|session" → Find existing code
4. WebSearch: "Node.js authentication best practices 2024"
5. WebSearch: "JWT vs session comparison"
6. WebFetch: "https://expressjs.com/en/advanced/best-practice-security.html"
7. Bash: git log --grep="auth" → Historical attempts

Findings:
- No existing auth system
- Express.js backend with REST API
- Microservices architecture (suggests JWT)
- Security requirements in docs
- Industry standard: JWT with refresh tokens

Research Documentation Template

After research, document findings:

## Research Findings for "[Prompt]"

**What was unclear:**
- [List ambiguities]

**Research executed:**
1. [Tool] - [What searched] - [Key finding]
2. [Tool] - [What searched] - [Key finding]

**Key discoveries:**
- [Important finding 1]
- [Important finding 2]
- [Pattern identified]
- [Constraint discovered]

**Options identified:**
1. [Option A] - [From research source]
2. [Option B] - [From research source]
3. [Option C] - [From research source]

**Questions to ask:**
- [Question 1 based on findings]
- [Question 2 based on findings]

Summary Checklist

Before asking questions:

• Created research plan with TodoWrite
• Checked conversation history for context
• Explored codebase for existing patterns
• Searched for similar implementations
• Reviewed relevant documentation
• Researched best practices (if needed)
• Documented findings
• Generated specific options from research
• Verified each option is grounded in findings
• Marked research phase complete in todo list

Critical Rules:

1. NEVER skip research phase
2. ALWAYS ground questions in findings
3. NEVER assume based on general knowledge
4. ALWAYS use conversation history first
5. DOCUMENT research findings before asking

Research is the foundation of effective clarification. The quality of your questions depends entirely on the thoroughness of your research.