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

• Existing patterns — how similar problems are solved

• Reusable components — what can be leveraged

• Conventions — naming, structure, architecture patterns

• Dependencies — libraries/frameworks in use

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

Phase 2: External Solutions (Standard)

• Best practices — industry standards for this problem

• Library options — available tools and tradeoffs

• 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

• Compare options — pros/cons matrix with weighted criteria

• Recommend approach — based on findings, with confidence level

• Flag risks — technical concerns and unknowns

• 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

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