Research Phase

Research sits between discovery and planning. Gather enough understanding to write a confident plan. Question assumptions, start with the smallest investigation that could answer the question, and scale up only when complexity warrants it.

When to Research

Enter research when:

• A feature exists (feature_create done)
• The problem involves unfamiliar code, external libraries, or multiple valid approaches
• You can't yet write a confident ## Discovery section for the plan

Skip research when the task is mechanical (rename, config change, straightforward addition) or you already have deep context from prior work.

Research Tiers

Your approach adapts to what tools are available.

Tier 1: Always Available

Codebase exploration -- Agent subagents

Use for understanding existing code, finding patterns, tracing data flow. Spawn focused subagents with one clear objective each.

memory_write({ feature: "my-feature", name: "research-existing-auth-patterns", content: "..." })

Web search -- WebSearch + WebFetch

Use for error messages, ecosystem comparisons, best practices. Save fetched content to a local file or memory immediately -- interrupted sessions lose unsaved fetches.

Tier 2: Context7

Available when: Context7 MCP server is configured.

Current library documentation, not stale training data. Use when:

• Checking API signatures for a specific library version
• Finding migration guides between versions
• Understanding framework patterns that change across releases
• Verifying that an approach is still the recommended one

Fallback: WebSearch for library docs. Note in findings that docs may be outdated relative to your target version.

Tier 3: NotebookLM

Available when: NotebookLM MCP server is configured.

Multi-source synthesis -- feed several documents and ask analytical questions. Use for:

• Comparing architectural approaches with trade-off analysis
• Synthesizing information from multiple docs/specs/codebases
• Generating structured analysis from unstructured sources
• Deep-diving into an unfamiliar domain

Research Patterns

Save all findings with memory_write -- see Organizing Findings below.

Organizing Findings

Every significant finding gets saved with memory_write scoped to the current feature. Structure each finding:

## Motivation
What question were we trying to answer? (1-2 lines, precise, no vague language)

## Findings
What did we learn? (methods, evidence, relevant files/sources)

## Implications
How does this affect the plan? (design decisions, constraints, recommendations)

## Limitations
What caveats apply? (confounders, incomplete coverage, assumptions made)

## Next Steps
What follow-up research would strengthen this finding? (optional -- only if gaps remain)

Name findings research-<discriminator> using: <area>, <lib>-api, <topic>-comparison, constraints, or <source>-notes.

Completion Criteria

Research is done when all five hold:

1. Problem understood -- explainable in one paragraph without hand-waving
2. Solution space mapped -- viable approaches and trade-offs known
3. Constraints identified -- technical, time, and dependency limits known
4. Key decisions ready -- major architectural choices can be made
5. No blocking unknowns -- remaining unknowns are explicitly accepted as limitations

If any criterion fails, target the specific gap. If a question can't be answered without building the thing, note it as a limitation and move on.

Transitioning to Planning

The plan's ## Discovery section is where research pays off. Reference your findings by name and write it as a confident summary -- motivation, key findings, implications, and acknowledged limitations. Not a log of what you did.

Tool Selection Quick Reference

[-->] = best tool for the job. Use the highest available tier. Fall back gracefully when tools aren't installed.