Pre-Work Research

Overview

Research before coding. Understand the landscape before changing it.

Core principle: Measure twice, cut once.

Announce at start: "I'm researching the codebase and documentation before implementing."

When to Research

Research is appropriate when:

Situation	Research Needed
Unfamiliar area of codebase	Yes
New library or API	Yes
Complex integration	Yes
Performance-sensitive code	Yes
Security-sensitive code	Yes
Simple, isolated change	Minimal

The Research Protocol

Step 1: Understand Requirements

Before researching implementation:

• Read the full issue description
• Review all acceptance criteria
• Note any constraints mentioned
• Identify unknowns

Step 2: Research Repository Documentation

# Project overview
cat README.md

# Architecture/design docs
ls -la docs/
find . -name "*.md" -path "./docs/*"

# Contributing guidelines
cat CONTRIBUTING.md

# API documentation
cat docs/api*.md
cat docs/architecture*.md

Look for:

• Architecture decisions
• Design patterns used
• Coding conventions
• Testing requirements
• Deployment considerations

Step 3: Research Existing Codebase

Find Similar Implementations

# Find similar features
grep -r "similar keyword" src/

# Find related tests
grep -r "similar keyword" **/*.test.*

# Find imports of relevant modules
grep -r "import.*ModuleName" src/

Understand Patterns

# How are similar things done?
# Look at 2-3 examples of similar functionality

# Example: If adding an API endpoint
grep -r "router\." src/routes/
cat src/routes/[existing-endpoint].ts

# Example: If adding a service
ls -la src/services/
cat src/services/[existing-service].ts

Check for Utilities

# What utilities exist?
ls -la src/utils/
cat src/utils/[relevant-util].ts

# Are there shared helpers?
grep -r "export function" src/utils/

Step 4: Research External Resources

When using external APIs or libraries:

Official Documentation

# Read the docs for dependencies
pnpm info [package-name]
# Then visit documentation URL

Search: "[library-name] documentation"
Search: "[library-name] getting started"
Search: "[library-name] [specific feature]"

API References

For external APIs:

• Authentication requirements
• Rate limits
• Error handling
• Response formats
• Versioning

Community Resources

• GitHub issues for common problems
• Stack Overflow for patterns
• Blog posts for best practices

Step 5: Document Findings

Create a research summary:

## Pre-Work Research: Issue #[NUMBER]

### Requirements Understanding
- [Key requirement 1]
- [Key requirement 2]

### Codebase Patterns
- Pattern for [X]: See `src/example/pattern.ts`
- Utilities available: `src/utils/helper.ts`
- Test pattern: See `src/example/example.test.ts`

### External Dependencies
- [Library]: [Key findings]
- [API]: [Authentication method, rate limits]

### Approach
Based on research, the approach is:
1. [Step 1]
2. [Step 2]
3. [Step 3]

### Risks/Considerations
- [Risk 1]
- [Consideration 1]

Step 6: Update Issue (If Significant)

If research reveals important context:

gh issue comment [ISSUE_NUMBER] --body "## Pre-Implementation Research

### Approach
[Summary of planned approach]

### Considerations
- [Important finding 1]
- [Important finding 2]

### Questions (if any)
- [Question needing clarification]
"

Research Depth by Task Size

Task Size	Research Depth
Trivial (typo, config)	None needed
Small (single file)	Quick pattern check
Medium (feature)	Full protocol
Large (system)	Extended research

Quick Pattern Check (5 min)

# Just verify pattern
grep -r "pattern" src/ | head -5
cat src/similar/example.ts | head -50

Full Protocol (15-30 min)

Complete Steps 1-6 above.

Extended Research (1+ hour)

• Read all relevant documentation
• Trace through existing implementations
• Create proof-of-concept if needed
• Document architectural considerations

What to Look For

In Documentation

Look For	Why
Architecture diagrams	Understand system structure
Coding standards	Match existing style
Decision records	Understand why things are done a way
API contracts	Maintain compatibility

In Codebase

Look For	Why
Similar features	Follow established patterns
Test patterns	Write consistent tests
Error handling	Handle errors consistently
Logging patterns	Log appropriately

In External Resources

Look For	Why
Official examples	Use recommended patterns
Common pitfalls	Avoid known issues
Performance tips	Optimize appropriately
Security guidance	Implement securely

Research Outputs

After research, you should know:

• How similar features are implemented
• What patterns to follow
• What utilities are available
• What the testing approach should be
• Any risks or special considerations

Checklist

Before starting implementation:

• Issue requirements understood
• Repository docs checked
• Similar code patterns found
• Relevant utilities identified
• External resources researched (if applicable)
• Approach documented
• Issue updated (if significant findings)

Integration

This skill is called by:

• issue-driven-development - Step 5

This skill informs:

• tdd-full-coverage - How to write tests
• strict-typing - Type patterns to use
• inline-documentation - Documentation patterns