research

/research — Focused Investigation

When to Use

• Evaluating whether a dependency has a newer version or has been superseded
• Finding community best practices for a specific technical problem
• Reading official documentation for an API or library
• Investigating how other projects solve a similar problem
• Checking if a pattern used in the codebase has known issues
• Any time you need external information before making a decision

Don't use when: the question has 3+ independent sub-questions (use /research-fleet for parallel scouts); you need to act on findings immediately (use /marshal which calls /research internally).

Protocol

Step 1: FORMULATE

Convert the research question into 2-4 specific search queries:

• Official docs query (e.g., "express.js middleware error handling docs")
• Community/GitHub query (e.g., "express error middleware best practices site:github.com")
• Technical blog/comparison query (e.g., "express vs fastify error handling 2025")
• Release notes query if version-specific (e.g., "express 5.x changelog breaking changes")

State the question clearly in one sentence before searching.

Step 2: SEARCH

Execute searches and read actual content (not just snippets):

• Use WebSearch for discovery, WebFetch for reading actual pages
• Evaluate source credibility: official docs > GitHub repos with stars > recent blog posts > forum answers
• Stop at 3-6 credible sources (not exhaustive — focused)
• If a source contradicts another, note the disagreement

Step 3: EXTRACT

For each finding, record:

• What: The specific fact, recommendation, or pattern discovered
• Source: URL or reference
• Relevance: How this applies to the original question (one sentence)
• Confidence: high (official docs, verified), medium (community consensus), low (single source, opinion)
• Action: What the codebase should do with this information (or "informational only")

Step 4: WRITE

Write findings to .planning/research/{topic-slug}.md:

# Research: {Topic}

> Question: {The original question}
> Date: {ISO date}
> Confidence: {overall: high/medium/low}

## Findings

### 1. {Finding title}
**What:** {description}
**Source:** {URL}
**Confidence:** {high/medium/low}
**Action:** {recommendation or "informational"}

### 2. {Finding title}
...

## Summary
{2-3 sentences: what was learned, what the recommendation is}

## Open Questions
{Anything that couldn't be resolved — needs human judgment or deeper investigation}

Step 5: RETURN

Return the summary and recommendation to the caller (user, Marshal, or Archon). The research document persists for future reference.

What /research Does NOT Do

• Make architectural decisions (that's the caller's job)
• Install packages or modify code
• Search exhaustively (2-4 queries, 3-6 sources, done)
• Evaluate subjective opinions as facts
• Recommend without evidence

Fringe Cases

• No web access available: Fall back to local-only research. Search the codebase, read docs files, check package.json, and produce findings from local sources. Note the limitation in the research document's confidence level.
• Search returns nothing relevant: Broaden the query (remove version-specific terms, try synonyms), try one more angle. If still empty, report uncertainty explicitly: "No strong evidence found. Recommend human review."
• .planning/research/ does not exist: Create it before writing the findings document. Never error on a missing output directory.
• Conflicting sources: Surface the conflict explicitly in the findings rather than silently picking one. Both sides belong in the document.
• Question is too broad for 3-6 sources: Narrow to the single most important sub-question, answer it well, and note what was scoped out. Suggest /research-fleet for multi-angle questions.

Contextual Gates

Reversibility: Green — writes one file to .planning/research/; delete to undo. Cost: No cost actions — web searches and one file write; no agents spawned, no confirmation needed. Trust: No gates — read-only investigation, safe at all trust levels.

Quality Gates

• Every finding must have a source URL
• Confidence levels must be justified (not guessed)
• Summary must answer the original question or state why it can't be answered
• Research document must be written before returning findings

Exit Protocol

Output findings summary, then:

---HANDOFF---
- Research: {topic}
- Findings: {count} sources analyzed
- Recommendation: {one-line summary}
- Document: .planning/research/{slug}.md
- Reversibility: green — one file written to .planning/research/; delete to undo
---