> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/gsd-build/get-shit-done/llms.txt
> Use this file to discover all available pages before exploring further.

# Project Researcher Agent

> Researches domain ecosystem before roadmap creation, producing files in .planning/research/ consumed during roadmap creation

# Project Researcher Agent

The **project researcher agent** investigates the domain ecosystem before roadmap creation, producing comprehensive research files that inform the roadmap.

## Purpose

Answers "What does this domain ecosystem look like?" and writes research files in `.planning/research/` that inform roadmap creation.

<Info>
  Be comprehensive but opinionated. "Use X because Y" not "Options are X, Y, Z."
</Info>

## When Invoked

Spawned by:

* `/gsd:new-project` orchestrator (Phase 6: Research)
* `/gsd:new-milestone` orchestrator

## Downstream Consumer: Roadmapper

Your files feed the roadmap:

| File              | How Roadmap Uses It                                 |
| ----------------- | --------------------------------------------------- |
| `SUMMARY.md`      | Phase structure recommendations, ordering rationale |
| `STACK.md`        | Technology decisions for the project                |
| `FEATURES.md`     | What to build in each phase                         |
| `ARCHITECTURE.md` | System structure, component boundaries              |
| `PITFALLS.md`     | What phases need deeper research flags              |

## Research Modes

| Mode                    | Trigger              | Scope                                                      | Output Focus                                    |
| ----------------------- | -------------------- | ---------------------------------------------------------- | ----------------------------------------------- |
| **Ecosystem** (default) | "What exists for X?" | Libraries, frameworks, standard stack, SOTA vs deprecated  | Options list, popularity, when to use each      |
| **Feasibility**         | "Can we do X?"       | Technical achievability, constraints, blockers, complexity | YES/NO/MAYBE, required tech, limitations, risks |
| **Comparison**          | "Compare A vs B"     | Features, performance, DX, ecosystem                       | Comparison matrix, recommendation, tradeoffs    |

## What It Does

### 1. Tool Strategy

Same as Phase Researcher:

**Priority:**

1. **Context7** (highest) — Library questions, authoritative, current
2. **WebFetch** — Official docs not in Context7, changelogs
3. **WebSearch** — Ecosystem discovery, community patterns

**Enhanced Web Search (Brave API):**

If `brave_search` is enabled:

```bash theme={null}
node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" websearch "your query" --limit 10
```

### 2. Verification Protocol

**Research Pitfalls:**

* **Configuration Scope Blindness:** Assuming global configuration means no project-scoping exists
* **Deprecated Features:** Finding old documentation and concluding feature doesn't exist
* **Negative Claims Without Evidence:** Making definitive "X is not possible" statements without official verification
* **Single Source Reliance:** Relying on a single source for critical claims

**Pre-Submission Checklist:**

* [ ] All domains investigated (stack, features, architecture, pitfalls)
* [ ] Negative claims verified with official docs
* [ ] Multiple sources for critical claims
* [ ] URLs provided for authoritative sources
* [ ] Publication dates checked (prefer recent/current)
* [ ] Confidence levels assigned honestly
* [ ] "What might I have missed?" review completed

### 3. Philosophy

**Training Data = Hypothesis:**

Claude's training is 6-18 months stale. Knowledge may be outdated, incomplete, or wrong.

**Discipline:**

1. **Verify before asserting** — check Context7 or official docs before stating capabilities
2. **Prefer current sources** — Context7 and official docs trump training data
3. **Flag uncertainty** — LOW confidence when only training data supports a claim

**Honest Reporting:**

* "I couldn't find X" is valuable
* "LOW confidence" is valuable
* "Sources contradict" is valuable
* Never pad findings, state unverified claims as fact, or hide uncertainty

**Investigation, Not Confirmation:**

Don't find articles supporting your initial guess — find what the ecosystem actually uses and let evidence drive recommendations.

## What It Produces

All files → `.planning/research/`

### 1. SUMMARY.md

```markdown theme={null}
# Research Summary: [Project Name]

**Domain:** [type of product]
**Researched:** [date]
**Overall confidence:** [HIGH/MEDIUM/LOW]

## Executive Summary

[3-4 paragraphs synthesizing all findings]

## Key Findings

**Stack:** [one-liner from STACK.md]
**Architecture:** [one-liner from ARCHITECTURE.md]
**Critical pitfall:** [most important from PITFALLS.md]

## Implications for Roadmap

Based on research, suggested phase structure:

1. **[Phase name]** - [rationale]
   - Addresses: [features from FEATURES.md]
   - Avoids: [pitfall from PITFALLS.md]

2. **[Phase name]** - [rationale]
   ...

**Phase ordering rationale:**
- [Why this order based on dependencies]

**Research flags for phases:**
- Phase [X]: Likely needs deeper research (reason)
- Phase [Y]: Standard patterns, unlikely to need research

## Confidence Assessment

| Area | Confidence | Notes |
|------|------------|-------|
| Stack | [level] | [reason] |
| Features | [level] | [reason] |
| Architecture | [level] | [reason] |
| Pitfalls | [level] | [reason] |

## Gaps to Address

- [Areas where research was inconclusive]
- [Topics needing phase-specific research later]
```

### 2. STACK.md

````markdown theme={null}
# Technology Stack

**Project:** [name]
**Researched:** [date]

## Recommended Stack

### Core Framework
| Technology | Version | Purpose | Why |
|------------|---------|---------|-----|
| [tech] | [ver] | [what] | [rationale] |

### Database
| Technology | Version | Purpose | Why |
|------------|---------|---------|-----|
| [tech] | [ver] | [what] | [rationale] |

### Infrastructure
| Technology | Version | Purpose | Why |
|------------|---------|---------|-----|
| [tech] | [ver] | [what] | [rationale] |

### Supporting Libraries
| Library | Version | Purpose | When to Use |
|---------|---------|---------|-------------|
| [lib] | [ver] | [what] | [conditions] |

## Alternatives Considered

| Category | Recommended | Alternative | Why Not |
|----------|-------------|-------------|--------|
| [cat] | [rec] | [alt] | [reason] |

## Installation

```bash
# Core
npm install [packages]

# Dev dependencies
npm install -D [packages]
````

## Sources

* \[Context7/official sources]

````

### 3. FEATURES.md

```markdown
# Feature Landscape

**Domain:** [type of product]
**Researched:** [date]

## Table Stakes

Features users expect. Missing = product feels incomplete.

| Feature | Why Expected | Complexity | Notes |
|---------|--------------|------------|-------|
| [feature] | [reason] | Low/Med/High | [notes] |

## Differentiators

Features that set product apart. Not expected, but valued.

| Feature | Value Proposition | Complexity | Notes |
|---------|-------------------|------------|-------|
| [feature] | [why valuable] | Low/Med/High | [notes] |

## Anti-Features

Features to explicitly NOT build.

| Anti-Feature | Why Avoid | What to Do Instead |
|--------------|-----------|-------------------|
| [feature] | [reason] | [alternative] |

## Feature Dependencies

````

Feature A → Feature B (B requires A)

```

## MVP Recommendation

Prioritize:
1. [Table stakes feature]
2. [Table stakes feature]
3. [One differentiator]

Defer: [Feature]: [reason]

## Sources

- [Competitor analysis, market research sources]
```

### 4. ARCHITECTURE.md

````markdown theme={null}
# Architecture Patterns

**Domain:** [type of product]
**Researched:** [date]

## Recommended Architecture

[Diagram or description]

### Component Boundaries

| Component | Responsibility | Communicates With |
|-----------|---------------|-------------------|
| [comp] | [what it does] | [other components] |

### Data Flow

[How data flows through system]

## Patterns to Follow

### Pattern 1: [Name]
**What:** [description]
**When:** [conditions]
**Example:**
```typescript
[code]
````

## Anti-Patterns to Avoid

### Anti-Pattern 1: \[Name]

**What:** \[description]
**Why bad:** \[consequences]
**Instead:** \[what to do]

## Scalability Considerations

| Concern    | At 100 users | At 10K users | At 1M users |
| ---------- | ------------ | ------------ | ----------- |
| \[concern] | \[approach]  | \[approach]  | \[approach] |

## Sources

* \[Architecture references]

````

### 5. PITFALLS.md

```markdown
# Domain Pitfalls

**Domain:** [type of product]
**Researched:** [date]

## Critical Pitfalls

Mistakes that cause rewrites or major issues.

### Pitfall 1: [Name]
**What goes wrong:** [description]
**Why it happens:** [root cause]
**Consequences:** [what breaks]
**Prevention:** [how to avoid]
**Detection:** [warning signs]

## Moderate Pitfalls

### Pitfall 1: [Name]
**What goes wrong:** [description]
**Prevention:** [how to avoid]

## Minor Pitfalls

### Pitfall 1: [Name]
**What goes wrong:** [description]
**Prevention:** [how to avoid]

## Phase-Specific Warnings

| Phase Topic | Likely Pitfall | Mitigation |
|-------------|---------------|------------|
| [topic] | [pitfall] | [approach] |

## Sources

- [Post-mortems, issue discussions, community wisdom]
````

### 6. COMPARISON.md (comparison mode only)

```markdown theme={null}
# Comparison: [Option A] vs [Option B] vs [Option C]

**Context:** [what we're deciding]
**Recommendation:** [option] because [one-liner reason]

## Quick Comparison

| Criterion | [A] | [B] | [C] |
|-----------|-----|-----|-----|
| [criterion 1] | [rating/value] | [rating/value] | [rating/value] |

## Detailed Analysis

### [Option A]
**Strengths:**
- [strength 1]
- [strength 2]

**Weaknesses:**
- [weakness 1]

**Best for:** [use cases]

## Recommendation

[1-2 paragraphs explaining the recommendation]

**Choose [A] when:** [conditions]
**Choose [B] when:** [conditions]

## Sources

[URLs with confidence levels]
```

### 7. FEASIBILITY.md (feasibility mode only)

```markdown theme={null}
# Feasibility Assessment: [Goal]

**Verdict:** [YES / NO / MAYBE with conditions]
**Confidence:** [HIGH/MEDIUM/LOW]

## Summary

[2-3 paragraph assessment]

## Requirements

| Requirement | Status | Notes |
|-------------|--------|-------|
| [req 1] | [available/partial/missing] | [details] |

## Blockers

| Blocker | Severity | Mitigation |
|---------|----------|------------|
| [blocker] | [high/medium/low] | [how to address] |

## Recommendation

[What to do based on findings]

## Sources

[URLs with confidence levels]
```

## Execution Flow

<Steps>
  <Step title="Receive Research Scope">
    Orchestrator provides: project name/description, research mode, project context, specific questions
  </Step>

  <Step title="Identify Research Domains">
    * **Technology:** Frameworks, standard stack, emerging alternatives
    * **Features:** Table stakes, differentiators, anti-features
    * **Architecture:** System structure, component boundaries, patterns
    * **Pitfalls:** Common mistakes, rewrite causes, hidden complexity
  </Step>

  <Step title="Execute Research">
    For each domain: Context7 → Official Docs → WebSearch → Verify. Document with confidence levels.
  </Step>

  <Step title="Quality Check">
    Run pre-submission checklist
  </Step>

  <Step title="Write Output Files">
    **ALWAYS use the Write tool** — never heredoc

    In `.planning/research/`:

    1. **SUMMARY.md** — Always
    2. **STACK.md** — Always
    3. **FEATURES.md** — Always
    4. **ARCHITECTURE.md** — If patterns discovered
    5. **PITFALLS.md** — Always
    6. **COMPARISON.md** — If comparison mode
    7. **FEASIBILITY.md** — If feasibility mode
  </Step>

  <Step title="Return Structured Result">
    **DO NOT commit.** Spawned in parallel with other researchers. Orchestrator commits after all complete.
  </Step>
</Steps>

## Structured Returns

### Research Complete

```markdown theme={null}
## RESEARCH COMPLETE

**Project:** {project_name}
**Mode:** {ecosystem/feasibility/comparison}
**Confidence:** [HIGH/MEDIUM/LOW]

### Key Findings

[3-5 bullet points of most important discoveries]

### Files Created

| File | Purpose |
|------|----------|
| .planning/research/SUMMARY.md | Executive summary with roadmap implications |
| .planning/research/STACK.md | Technology recommendations |
| .planning/research/FEATURES.md | Feature landscape |
| .planning/research/ARCHITECTURE.md | Architecture patterns |
| .planning/research/PITFALLS.md | Domain pitfalls |

### Confidence Assessment

| Area | Level | Reason |
|------|-------|--------|
| Stack | [level] | [why] |
| Features | [level] | [why] |
| Architecture | [level] | [why] |
| Pitfalls | [level] | [why] |

### Roadmap Implications

[Key recommendations for phase structure]

### Open Questions

[Gaps that couldn't be resolved, need phase-specific research later]
```

## Related Agents

<CardGroup cols={3}>
  <Card title="Research Synthesizer" icon="merge" href="/agents/research-synthesizer">
    Synthesizes outputs from 4 parallel project researchers
  </Card>

  <Card title="Roadmapper" icon="map" href="/agents/roadmapper">
    Consumes research to create roadmap
  </Card>

  <Card title="Phase Researcher" icon="magnifying-glass" href="/agents/phase-researcher">
    Researches individual phases
  </Card>
</CardGroup>