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

Identify research topics from the current story's researchTopics field
Fetch third-party library source code if needed
Search documentation and best practices
Analyze and compare alternatives
Generate a research report
Update knowledge base with findings
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

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

Verify stability:
- Released at least 1-2 weeks ago (not bleeding edge)
- Check GitHub issues for critical bugs
- Review changelog for breaking changes
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):

README.md - Understand design intent and quick-start examples
Entry Point Files:
- Rust: src/lib.rs, src/main.rs
- TypeScript/JS: src/index.ts, index.js
- Python: __init__.py, main.py
Module Structure - Scan mod.rs files or directory structure
Type Definitions - Find core structs, interfaces, types
Target Functionality - Locate the specific feature you need
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

Step 4: Web Search for Context

Search for:

Official documentation
Best practices and common patterns
Known issues and gotchas
Performance considerations
Alternative libraries

Use MCP tools like context7 for up-to-date documentation.

Step 5: Compare Alternatives (If Applicable)

When multiple solutions exist, create a comparison:

Criterion	Option A	Option B	Option C
Performance	...	...	...
API Ergonomics	...	...	...
Maintenance Status	...	...	...
Bundle Size	...	...	...
Learning Curve	...	...	...

Include a recommendation with reasoning.

Research Report Template

Save to: scripts/aha-loop/research/[story-id]-research.md

# Research Report: [Story ID] - [Story Title]

**Date:** YYYY-MM-DD
**Status:** Complete | Needs Follow-up

## Research Topics

1. [Topic from researchTopics array]
2. ...

## Findings

### Topic 1: [Name]

**Summary:** Brief answer to the research question

**Source Code Analysis:**
- Library: [name] v[version]
- Key File: `.vendor/rust/tokio-1.35.0/src/runtime/mod.rs`
- Relevant Code: Lines 123-189
- Pattern Observed: [description]

**Documentation Notes:**
- [Key insight from docs]
- [Another insight]

**Code Example:**
```[language]
// Example from source or docs

Topic 2: [Name]

...

Alternatives Comparison

Criterion	Option A	Option B	Recommendation
...	...	...	...

Recommendation: [Option X] because [reasoning]

Implementation Recommendations

Based on research, the story should be implemented as follows:

[Specific implementation guidance]
[Pattern to follow]
[Pitfalls to avoid]

Follow-up Research Needed

[Topic that needs deeper investigation]
[Question that emerged during research]

Knowledge Base Updates

The following should be added to knowledge base:

To knowledge/project/patterns.md:

[Pattern specific to this project]

To knowledge/domain/[topic]/:

[Reusable knowledge about a library or technique]


---

## Updating Knowledge Base

### Project Knowledge (`knowledge/project/`)

Add patterns specific to THIS project:
- How this codebase uses a library
- Project-specific conventions discovered
- Gotchas specific to this codebase

### Domain Knowledge (`knowledge/domain/`)

Add reusable technical knowledge:
- Library usage patterns (applicable to any project)
- Comparison documents
- Best practices

**Create new topic directories as needed:**

knowledge/domain/ └── [topic-name]/ ├── README.md # Overview ├── patterns.md # Common patterns ├── gotchas.md # Known issues └── examples/ # Code examples


---

## Source Code Reading Report

When you read library source code, document your findings:

```markdown
## Source Code Analysis: [Library] v[Version]

### Module Structure

src/ ├── lib.rs # Main entry, exports public API ├── runtime/ # Async runtime implementation │ ├── mod.rs # Module exports │ └── scheduler.rs # Task scheduling └── sync/ # Synchronization primitives


### Key Types

- `Runtime` (src/runtime/mod.rs:45) - Main runtime struct
- `Handle` (src/runtime/handle.rs:23) - Runtime handle for spawning

### Key Functions

- `Runtime::new()` (L89-L120) - Creates new runtime with default config
- `spawn()` (L156-L189) - Spawns a new async task

### Usage Patterns from Tests

From `tests/runtime.rs:34`:
```rust
let rt = Runtime::new().unwrap();
rt.block_on(async {
    // ...
});

Important Notes

Thread safety: Runtime is Send + Sync
Performance: Use spawn_blocking for CPU-heavy tasks
Gotcha: Don't call block_on from async context


---

## Checklist

Before marking research complete:

- [ ] All `researchTopics` investigated
- [ ] Library source code fetched and key files read (if applicable)
- [ ] Web search performed for documentation and best practices
- [ ] Alternatives compared (if multiple options exist)
- [ ] Research report saved to `scripts/aha-loop/research/`
- [ ] Knowledge base updated with reusable findings
- [ ] Implementation recommendations documented
- [ ] `researchCompleted: true` set in prd.json