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