research-phase

If dispatched as a research subagent yourself, skip this skill — you are the worker, not the orchestrator. Just answer the prompt you were given.

Research Phase

This is Phase 2 of marten-workflow. Its job: replace assumption-based planning with evidence-based planning. Output is a written research report that feeds directly into Phase 3 (writing-plans).

Why This Phase Exists

Skipping research causes:

• Plans built on outdated APIs or deprecated patterns
• Reinvention of solved problems instead of using established libraries
• Conflicts with existing codebase patterns the planner didn't notice

Martin's global rules already mandate "research before implementing" and "≥2 subagents per topic". This skill operationalizes both.

Hard Rules (non-negotiable)

1. Dispatch ≥2 subagents per research topic — single subagent = single point of view, prone to blind spots.
2. Subagents must use WebSearch and WebFetch only. Chrome MCP (mcp__claude-in-chrome__*) is banned inside research subagents. Include this ban explicitly in every dispatch prompt.
3. Run web research and codebase research as separate subagent groups — do not let one subagent do both, the prompts compete for attention.
4. Dispatch all subagents in parallel in a single tool message when topics are independent.
5. Reconcile conflicts in the report — when subagents disagree, surface the disagreement, do not silently pick a side.

Inputs

Before starting, confirm Phase 1 (brainstorming) produced:

• A clear problem statement
• A list of open questions / unknowns
• Candidate approaches to evaluate

If brainstorming output is missing or thin, return to Phase 1 first.

Step-by-step

1. Decompose into research topics

Break the brainstorming output into 2–5 narrow research topics. Each topic must be answerable with primary-source evidence. Examples:

• "What library does the Laravel/Inertia ecosystem use for X in 2026?"
• "How does this codebase currently handle Y? Where are the patterns?"
• "What are the documented breaking changes between v3 and v4 of Z?"

Avoid topics like "is this a good idea?" — that's Phase 1 territory.

2. Decide subagent type per topic

Topic flavor	Subagent type	Tools
Web facts, library research, API docs	general-purpose (research only)	WebSearch, WebFetch
Codebase patterns, file locations, existing impls	Explore	Read-only filesystem + grep
Independent verification of disputed fact	scientist-researcher	WebSearch, WebFetch

3. Brief each subagent narrowly

Every subagent prompt must include:

• The single topic, phrased as a concrete question
• Required output format (markdown bullets, source URLs, confidence rating 1–10)
• Word-count cap (typically 250–400 words)
• Explicit ban: "Do NOT use any mcp__claude-in-chrome__* tools. Use only WebSearch and WebFetch."
• Source preference: official docs > GitHub repos > recent blog posts > older forums. Avoid sources older than 2 years unless necessary.
• Credibility scoring: each source gets a 1–10 credibility rating with brief reasoning.

4. Dispatch in parallel

Use a single message with multiple Agent tool calls. Pair web+web (different angles) or web+codebase per topic.

5. Reconcile

When all subagents return:

• Agreement → high confidence, proceed
• Disagreement on facts → spawn one tie-breaker subagent with the conflict explicit in the prompt
• Disagreement on judgment → record both sides in the report, let Phase 3 pick

6. Write the report

Save to research-report.md at the worktree root (or repo root if worktree not yet created). Format:

# Research Report — <topic>

## Topics investigated
1. <topic 1>
2. <topic 2>
...

## Findings

### Topic 1: <question>
**Answer:** <one-sentence answer>
**Confidence:** <high|medium|low>
**Evidence:**
- <bullet> ([source](url), credibility 8/10)
- <bullet> ([source](url), credibility 7/10)
**Conflicts:** <any disagreements + resolution>

### Topic 2: ...

## Recommendations for the plan
- <actionable recommendation 1>
- <actionable recommendation 2>

## Open questions (defer to user)
- <anything subagents could not resolve>

7. Hand off

Tell the user:

"Research phase complete. Report at research-report.md. Key findings: <2-3 bullet summary>. Open questions: . Ready for Phase 3 (writing-plans)."

If open questions exist, ask the user before proceeding — do not auto-resolve.

Anti-patterns

• ❌ Doing web search directly in the main thread (blows the context window)
• ❌ Single subagent per topic ("I'll triangulate later") — doesn't happen
• ❌ Letting research drift into design ("while researching I also planned…")
• ❌ Skipping the report file ("I'll just remember it") — Phase 3 needs the artifact, especially across session resumes

Banned-tool reminder template

Paste verbatim into every research subagent prompt:

Tool restrictions: Use only WebSearch and WebFetch for web work, and Read/Grep/Glob for codebase work. Do NOT use any mcp__claude-in-chrome__* tools — Chrome MCP is reserved for the main thread with explicit user consent. Violating this is a hard error.