focused-technical-research

source	shipped
name	focused-technical-research
description	Use when external library, framework, API, or architecture research must be isolated from implementation context
type	colony
domains	["research","evaluation","comparison","technology-selection"]
agent_roles	["oracle","scout","architect"]
workflow_triggers	["plan","build"]
task_keywords	["research","framework","library","api","sdk","compare","recommendation"]
priority	normal
version	1.0

Focused Technical Research

Purpose

Focused research in a context-isolated sandbox. When a phase needs answers about external tools, frameworks, or patterns, this skill investigates without polluting the main planning conversation. It produces a self-contained RESEARCH.md with findings, comparisons, and recommendations that the planner can consume on demand -- like sending a scout ahead while the party camps.

When to Use

• The phase needs a technology or framework choice and you don't know the options
• Integration with an external service requires understanding its API, SDK, or limitations
• Multiple implementation approaches exist and trade-offs aren't clear
• A spike revealed that more research is needed before deciding
• You need to understand a domain concept before designing a solution

Instructions

1. Frame the Research Question

Define what you need to know, why, and what decision it informs:

## Research Brief

**Question:** {what you need to learn}
**Why:** {what decision this research unblocks}
**Scope:** {what's in scope, what's explicitly out of scope}
**Time budget:** {1-3 hours}
**Decision criteria:** {what makes one option better than another for this project}

Example briefs:

Question	Decision It Unblocks	Decision Criteria
"Which real-time library fits our stack?"	WebSocket/SSE choice for presence feature	Bundle size, server requirements, browser support
"How does Stripe handle multi-currency?"	Payment architecture for international launch	Fee structure, API complexity, PCI scope
"What are the options for offline data sync?"	Mobile-first architecture decision	Conflict resolution, storage limits, sync reliability

2. Conduct Focused Research

Investigate within the defined scope. For each option or approach:

A. Gather evidence:

• Official documentation (prefer docs over blog posts for accuracy)
• GitHub repo health (stars, recent commits, issue response time, release frequency)
• Bundle size or performance benchmarks if relevant
• Known limitations and common complaints (check GitHub issues)
• Community size and ecosystem (plugins, tutorials, Stack Overflow activity)

B. Test mental model:

• Can you explain how it works in 3 sentences?
• What's the "hello world" look like? (Complexity of basic usage)
• Where does it get complicated? (Every tool has its rough edge)

C. Evaluate against criteria:

• Score each option against the decision criteria
• Note where information is incomplete (honesty > confidence)

3. Structure the Comparison

Present findings in a decision-friendly format:

## Options Comparison

| Criterion | Option A | Option B | Option C |
|-----------|----------|----------|----------|
| {criterion 1} | {finding} | {finding} | {finding} |
| {criterion 2} | {finding} | {finding} | {finding} |
| {criterion 3} | {finding} | {finding} | {finding} |
| **Overall fit** | {score} | {score} | {score} |

4. Make a Recommendation

Pick a winner and explain why:

## Recommendation: {option}

**Why:** {2-3 sentences connecting the choice to project-specific needs}
**Trade-offs:** {what you gain and what you give up}
**Conditions where this is wrong:** {when would you pick differently}

5. Produce RESEARCH.md

Assemble the full research document:

# Research: {topic}

**Date:** {date}
**Question:** {original question}
**Recommendation:** {short answer}

## Context
{why this research was needed, what decision it informs}

## Options Investigated
{detailed findings for each option}

## Comparison Matrix
{structured comparison table}

## Recommendation
{chosen option with reasoning}

## Implementation Notes
{practical guidance for the builder -- gotchas, setup steps, common patterns}

## References
{links to docs, repos, articles that were consulted}

## Gaps
{what you couldn't find out, what remains uncertain -- be honest}

6. Return to Caller

Hand off the research cleanly:

• Summarize the recommendation in 2-3 sentences
• Point to the RESEARCH.md file for full details
• Note any gaps or uncertainties that might affect the decision
• The main planning context never needs to see the investigation process -- only the findings

Key Patterns

The Depth-First Pattern

When comparing options, go deep on the top 2-3 before going wide. Surface-level comparison of 10 options is less useful than thorough evaluation of the 3 that actually matter.

The Bad News Pattern

Actively look for reasons NOT to choose each option. The thing that breaks at scale, the API that's deprecated, the dependency that hasn't been updated in 2 years. Bad news is more valuable than good news in research.

The Hello World Complexity Pattern

If the basic usage example is hard to understand, the advanced usage will be impossible. First impressions of developer experience are remarkably predictive.

The Ecosystem Check

A great library with no community is a risk. Check: when was the last commit? How many open issues? Are maintainers responsive? Is there a migration path if it gets abandoned?

The Honest Gap Pattern

Never fill knowledge gaps with assumptions. If the docs don't say whether it handles a case, write "unclear" not "probably fine." Uncertainty documented is better than uncertainty hidden.

Output Format

• Creates research/{topic-slug}/RESEARCH.md with full findings
• Returns recommendation summary to the calling context
• The research directory is isolated -- doesn't pollute planning artifacts

Examples

Example 1: Library comparison

Human: "Need to pick a state management library for the new frontend. Not sure what's current."
Isolator: Framing research: "Which state management approach best fits a React app with real-time data updates and offline support?"
Researching: Redux Toolkit, Zustand, Jotai, and TanStack Query for server-state...
[conducts research]
Recommendation: TanStack Query for server state + Zustand for client state. Reasoning: real-time data is mostly server state, and TQ handles caching/revalidation beautifully. Zustand covers the small amount of client-only state without boilerplate.
Full comparison in research/state-management/RESEARCH.md

Example 2: API integration research

Human: "We need to integrate with Notion's API for the content import feature."
Isolator: Framing research: "What are the capabilities, rate limits, and gotchas of Notion's API for bulk content import?"
Investigating Notion API docs, rate limits, authentication, and known issues...
[conducts research]
Findings: Notion API has a 3 requests/second rate limit, no bulk export endpoint, and rich text blocks need recursive parsing. Content import for 1000+ pages will need a rate-limited queue with retry logic.
Full details in research/notion-api/RESEARCH.md

Example 3: Architecture research

Human: "Should we use microservices or a monolith for the backend?"
Isolator: Framing research: "Which backend architecture fits a 2-person team building a SaaS with <10k users in year one?"
Researching trade-offs for team size, deployment complexity, and scaling timeline...
[conducts research]
Recommendation: Modular monolith. Reasoning: At current team size and user count, microservices overhead (deployment, observability, network complexity) outweighs benefits. Design modules with clean boundaries now, split later if needed.
Analysis in research/backend-architecture/RESEARCH.md