Research

Deep Research Skill

Conduct thorough technical research before implementation to ensure high-quality, informed decisions.

Workspace Mode Note

When running in workspace mode, all paths are relative to .aha-loop/ directory:

• Research reports: .aha-loop/research/ (not scripts/aha-loop/research/)
• Knowledge base: .aha-loop/knowledge/ (not knowledge/)
• Vendor directory: .aha-loop/.vendor/ (not .vendor/)

The orchestrator will provide the actual paths in the prompt context.

The Job

1. Identify research topics from the current story's researchTopics field
2. Fetch third-party library source code if needed
3. Search documentation and best practices
4. Analyze and compare alternatives
5. Generate a research report
6. Update knowledge base with findings
7. Mark researchCompleted: true in prd.json

Research Process

Step 1: Identify What to Research

Read the current story from prd.json and extract:

• researchTopics - explicit topics to investigate
• Dependencies mentioned in acceptance criteria
• Patterns referenced in the description

Also check:

• Previous story's learnings field for follow-up research needs
• knowledge/project/gotchas.md for related known issues

Step 2: Fetch Library Source Code (If Needed)

For any third-party library research, fetch the source:

# Fetch specific library
./scripts/aha-loop/fetch-source.sh rust tokio 1.35.0

# Or fetch all project dependencies
./scripts/aha-loop/fetch-source.sh --from-deps

After fetching, the source will be at .vendor/<ecosystem>/<name>-<version>/

Library Version Selection

Always Prefer Latest Stable Versions

When researching or recommending libraries, always check for and prefer the latest stable version unless there's a specific compatibility reason not to.

Version Research Process

1. Query the package registry for latest version:

   # Rust (crates.io)
   curl -s "https://crates.io/api/v1/crates/tokio" | jq '.crate.max_stable_version'
   
   # Or use cargo
   cargo search tokio --limit 1
   
   # Node.js (npm)
   npm view react version
   
   # Python (PyPI)
   pip index versions requests 2>/dev/null | head -1

2. Verify stability:

   • Released at least 1-2 weeks ago (not bleeding edge)
   • Check GitHub issues for critical bugs
   • Review changelog for breaking changes

3. Check compatibility:

   • Works with existing project dependencies
   • Compatible with project's minimum supported language version
   • No known conflicts

Version Documentation

Always document version decisions:

## Version Decision: [Library Name]

**Selected Version:** X.Y.Z
**Latest Available:** X.Y.Z (as of YYYY-MM-DD)
**Reason:** [Why this version was chosen]

**Compatibility Notes:**
- Works with [other dependency] v[X.Y]
- Requires [language] v[X.Y]+

When to Use Older Versions

Only use older versions when:

• Latest version has critical bugs
• Incompatible with required dependencies
• Breaking changes require significant refactoring
• Project explicitly constrains the version

Always document the reason in knowledge/project/decisions.md:

### ADR: Using [Library] v[Old] instead of v[New]

**Context:** [Why we're not using latest]
**Decision:** Pin to v[Old]
**Consequences:** [What we're missing, when to revisit]

Step 3: Read Source Code Strategically

Reading Order (Most Important First):

1. README.md - Understand design intent and quick-start examples
2. Entry Point Files:
   • Rust: src/lib.rs, src/main.rs
   • TypeScript/JS: src/index.ts, index.js
   • Python: __init__.py, main.py
3. Module Structure - Scan mod.rs files or directory structure
4. Type Definitions - Find core structs, interfaces, types
5. Target Functionality - Locate the specific feature you need
6. Tests - Learn correct usage patterns from test files

Reading Tips:

• Use semantic search to find relevant code sections
• Focus on PUBLIC APIs, skip internal implementation unless needed
• Look for examples/ directory for usage patterns
• Check tests/ for edge cases and proper usage