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:

// 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