sdd-research

name	sdd-research
description	Pattern investigation and technical research before specification. Use when technical approach is unclear, exploring existing solutions, or analyzing codebase patterns. Supports deep research mode for thorough external investigation.

SDD Research Skill

Investigate codebase patterns and external solutions to inform specification and planning. Supports two modes: standard (codebase-focused) and deep (comprehensive external investigation).

When to Use

• Technical approach is unclear
• Need to understand existing patterns
• Evaluating solution options
• Before /specify or /plan commands
• Deep research: New domain, unfamiliar technology, high-stakes architectural decision, or when standard research yields insufficient clarity

Research Modes

Standard Research (default)

Quick internal + surface external analysis. Good for well-understood domains where the codebase already has relevant patterns.

Deep Research

Multi-pass external investigation using web search and documentation fetching. Use when:

• Entering an unfamiliar technology domain
• Comparing multiple complex solutions (e.g. auth providers, database engines, deployment platforms)
• The decision has high cost-of-reversal (architecture, data model, vendor lock-in)
• Standard research leaves too many unknowns

Trigger: User requests deep research explicitly, or the agent detects high uncertainty after Phase 1.

Research Protocol

Phase 1: Codebase Analysis

1. Existing patterns — how similar problems are solved
2. Reusable components — what can be leveraged
3. Conventions — naming, structure, architecture patterns
4. Dependencies — libraries/frameworks in use

Run scripts/scan-patterns.sh to auto-detect project stack before manual exploration.

Phase 2: External Solutions (Standard)

1. Best practices — industry standards for this problem
2. Library options — available tools and tradeoffs
3. Architecture patterns — applicable design patterns

Phase 2-Deep: Deep External Research (when deep mode is active)

Perform iterative, multi-pass investigation:

Pass 1 — Landscape scan:

• Use WebSearch to survey the solution space (e.g. "best [technology] for [use case] 2026")
• Identify the top 3-5 candidates from search results
• Note official documentation URLs for each candidate

Pass 2 — Documentation deep-dive:

• Use WebFetch to read official docs, getting-started guides, and API references for each candidate
• Extract: API surface, pricing model, limits, supported platforms, migration path
• Note version numbers and last-updated dates (reject stale/abandoned projects)

Pass 3 — Real-world validation:

• Search for "[candidate] vs [candidate]" comparisons, benchmarks, and post-mortems
• Search for "[candidate] production issues" or "[candidate] limitations"
• Look for community size indicators: GitHub stars, npm weekly downloads, Stack Overflow activity

Pass 4 — Integration feasibility:

• Check compatibility with the project's detected stack (from Phase 1)
• Search for "[candidate] + [framework]" integration guides
• Identify required changes to existing architecture

Deep research output additions:

• Source URLs for all claims (linked in the research doc)
• Confidence level per finding (High / Medium / Low — based on source quality)
• "Last verified" date for each external fact

Phase 3: Synthesis

1. Compare options — pros/cons matrix with weighted criteria
2. Recommend approach — based on findings, with confidence level
3. Flag risks — technical concerns and unknowns
4. Deep research only: Include source bibliography and confidence assessment

Output Format

# Research: [Topic]

## Summary
[1-2 sentence overview]
**Research mode:** Standard | Deep
**Confidence:** High | Medium | Low

## Codebase Analysis
### Existing Patterns
| Pattern | Location | Relevance |

### Reusable Components
- [component]: [how to leverage]

## External Solutions
### Option 1: [Name]
- **Pros**: | **Cons**: | **Effort**:
- **Source**: [URL] (deep research only)

## Comparison Matrix
| Criteria | Weight | Option 1 | Option 2 |

## Recommendation
[Recommended approach with rationale]
**Confidence:** [High/Medium/Low] — [why]

## Risks & Unknowns
- [risk]: [mitigation]

## Sources (deep research only)
- [URL]: [what was learned]

References

• references/patterns.md — Common architectural patterns
• references/deep-research-guide.md — Deep research methodology, search strategies, and source evaluation criteria

Scripts

• scripts/scan-patterns.sh [project-root] — Auto-detect frameworks, languages, testing tools, and project structure conventions

Integration

• Findings feed into /specify and sdd-planner subagent
• Can be invoked by sdd-explorer for deeper analysis
• Use the ask question tool when research reveals multiple valid approaches
• Deep research mode uses WebSearch and WebFetch tools extensively — ensure sandbox allows outbound access