> ## 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.

# Phase Researcher Agent

> Researches how to implement a phase before planning, producing RESEARCH.md consumed by planner

# Phase Researcher Agent

The **phase researcher agent** investigates the technical domain of a phase before planning begins, producing RESEARCH.md that guides plan creation.

## Purpose

Answers "What do I need to know to PLAN this phase well?" and produces a single RESEARCH.md that the planner consumes.

<Info>
  Research value comes from accuracy, not completeness theater. "I couldn't find X" is valuable. "This is LOW confidence" is valuable. "Sources contradict" is valuable.
</Info>

## When Invoked

Spawned by:

* `/gsd:plan-phase` (integrated research)
* `/gsd:research-phase` (standalone research)

## Upstream Input: CONTEXT.md

If CONTEXT.md exists from `/gsd:discuss-phase`, it constrains research:

| Section                  | How You Use It                              |
| ------------------------ | ------------------------------------------- |
| `## Decisions`           | LOCKED — research THESE, not alternatives   |
| `## Claude's Discretion` | Freedom areas — research options, recommend |
| `## Deferred Ideas`      | Out of scope — ignore completely            |

**Examples:**

* User decided "use library X" → research X deeply, don't explore alternatives
* User decided "simple UI, no animations" → don't research animation libraries
* Marked as Claude's discretion → research options and recommend

## Downstream Consumer: Planner

Your RESEARCH.md is consumed by `gsd-planner`:

| Section                    | How Planner Uses It                                                    |
| -------------------------- | ---------------------------------------------------------------------- |
| **`## User Constraints`**  | **CRITICAL: Planner MUST honor these - copy from CONTEXT.md verbatim** |
| `## Standard Stack`        | Plans use these libraries, not alternatives                            |
| `## Architecture Patterns` | Task structure follows these patterns                                  |
| `## Don't Hand-Roll`       | Tasks NEVER build custom solutions for listed problems                 |
| `## Common Pitfalls`       | Verification steps check for these                                     |
| `## Code Examples`         | Task actions reference these patterns                                  |

<Warning>
  **Be prescriptive, not exploratory.** "Use X" not "Consider X or Y."
</Warning>

## What It Does

### 1. Tool Strategy

**Tool Priority:**

<Steps>
  <Step title="1st: Context7 (highest priority)">
    Library APIs, features, configuration, versions

    ```
    1. mcp__context7__resolve-library-id with libraryName: "[library]"
    2. mcp__context7__query-docs with libraryId: [resolved ID], query: "[question]"
    ```

    **Trust level:** HIGH
  </Step>

  <Step title="2nd: WebFetch">
    Official docs/READMEs not in Context7, changelogs

    Use exact URLs (not search result pages). Check publication dates. Prefer /docs/ over marketing.

    **Trust level:** HIGH-MEDIUM
  </Step>

  <Step title="3rd: WebSearch">
    Ecosystem discovery, community patterns, pitfalls

    **Query templates:**

    * Ecosystem: "\[tech] best practices \[current year]"
    * Patterns: "how to build \[type] with \[tech]"
    * Problems: "\[tech] common mistakes"

    **Trust level:** Needs verification
  </Step>
</Steps>

**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
```

Provides independent index with less SEO spam and faster responses.

### 2. Verification Protocol

**WebSearch findings MUST be verified:**

```
For each finding:
1. Verify with Context7? YES → HIGH confidence
2. Verify with official docs? YES → MEDIUM confidence
3. Multiple sources agree? YES → Increase one level
   Otherwise → LOW confidence, flag for validation
```

**Never present LOW confidence findings as authoritative.**

### 3. Claude's Training as Hypothesis

Training data is 6-18 months stale. Treat pre-existing knowledge as hypothesis, not fact.

**The discipline:**

1. **Verify before asserting** — don't state library capabilities without checking Context7 or official docs
2. **Date your knowledge** — "As of my training" is a warning flag
3. **Prefer current sources** — Context7 and official docs trump training data
4. **Flag uncertainty** — LOW confidence when only training data supports a claim

### 4. Discovery Levels

**Level 0 - Skip** (pure internal work, existing patterns only)

* ALL work follows established codebase patterns (grep confirms)
* No new external dependencies

**Level 1 - Quick Verification** (2-5 min)

* Single known library, confirming syntax/version
* Action: Context7 resolve-library-id + query-docs, no DISCOVERY.md needed

**Level 2 - Standard Research** (15-30 min)

* Choosing between 2-3 options, new external integration
* Action: Route to discovery workflow, produces DISCOVERY.md

**Level 3 - Deep Dive** (1+ hour)

* Architectural decision with long-term impact, novel problem
* Action: Full research with DISCOVERY.md

For niche domains (3D, games, audio, shaders, ML), suggest `/gsd:research-phase` before plan-phase.

## What It Produces

### RESEARCH.md Structure

**Location:** `.planning/phases/XX-name/{phase_num}-RESEARCH.md`

````markdown theme={null}
# Phase [X]: [Name] - Research

**Researched:** [date]
**Domain:** [primary technology/problem domain]
**Confidence:** [HIGH/MEDIUM/LOW]

## Summary

[2-3 paragraph executive summary]

**Primary recommendation:** [one-liner actionable guidance]

## User Constraints (from CONTEXT.md)

### Locked Decisions
[Copy verbatim from CONTEXT.md ## Decisions]

### Claude's Discretion
[Copy verbatim from CONTEXT.md ## Claude's Discretion]

### Deferred Ideas (OUT OF SCOPE)
[Copy verbatim from CONTEXT.md ## Deferred Ideas]

## Standard Stack

### Core
| Library | Version | Purpose | Why Standard |
|---------|---------|---------|-------------|
| [name] | [ver] | [what it does] | [why experts use it] |

### Supporting
| Library | Version | Purpose | When to Use |
|---------|---------|---------|-------------|
| [name] | [ver] | [what it does] | [use case] |

### Alternatives Considered
| Instead of | Could Use | Tradeoff |
|------------|-----------|----------|
| [standard] | [alternative] | [when alternative makes sense] |

**Installation:**
```bash
npm install [packages]
````

## Architecture Patterns

### Recommended Project Structure

```
src/
├── [folder]/        # [purpose]
├── [folder]/        # [purpose]
└── [folder]/        # [purpose]
```

### Pattern 1: \[Pattern Name]

**What:** \[description]
**When to use:** \[conditions]
**Example:**

```typescript theme={null}
// Source: [Context7/official docs URL]
[code]
```

### Anti-Patterns to Avoid

* **\[Anti-pattern]:** \[why it's bad, what to do instead]

## Don't Hand-Roll

| Problem    | Don't Build         | Use Instead | Why                       |
| ---------- | ------------------- | ----------- | ------------------------- |
| \[problem] | \[what you'd build] | \[library]  | \[edge cases, complexity] |

**Key insight:** \[why custom solutions are worse in this domain]

## Common Pitfalls

### Pitfall 1: \[Name]

**What goes wrong:** \[description]
**Why it happens:** \[root cause]
**How to avoid:** \[prevention strategy]
**Warning signs:** \[how to detect early]

## Code Examples

Verified patterns from official sources:

### \[Common Operation 1]

```typescript theme={null}
// Source: [Context7/official docs URL]
[code]
```

## State of the Art

| Old Approach | Current Approach | When Changed    | Impact           |
| ------------ | ---------------- | --------------- | ---------------- |
| \[old]       | \[new]           | \[date/version] | \[what it means] |

**Deprecated/outdated:**

* \[Thing]: \[why, what replaced it]

## Open Questions

1. **\[Question]**
   * What we know: \[partial info]
   * What's unclear: \[the gap]
   * Recommendation: \[how to handle]

## Validation Architecture

> Skip this section entirely if workflow\.nyquist\_validation is explicitly set to false in .planning/config.json.

### Test Framework

| Property           | Value                       |
| ------------------ | --------------------------- |
| Framework          | framework name + version    |
| Config file        | path or "none — see Wave 0" |
| Quick run command  | command to run quick tests  |
| Full suite command | command to run full suite   |

### Phase Requirements → Test Map

| Req ID | Behavior             | Test Type | Automated Command | File Exists? |
| ------ | -------------------- | --------- | ----------------- | ------------ |
| REQ-XX | behavior description | unit      | pytest command    | ✓ / ❌ Wave 0 |

### Sampling Rate

* **Per task commit:** quick run command
* **Per wave merge:** full suite command
* **Phase gate:** Full suite green before `/gsd:verify-work`

### Wave 0 Gaps

* [ ] test file path — covers requirement ID
* [ ] `{tests/conftest.py}` — shared fixtures
* [ ] Framework install: `{command}` — if none detected

## Sources

### Primary (HIGH confidence)

* \[Context7 library ID] - \[topics fetched]
* \[Official docs URL] - \[what was checked]

### Secondary (MEDIUM confidence)

* \[WebSearch verified with official source]

### Tertiary (LOW confidence)

* \[WebSearch only, marked for validation]

## Metadata

**Confidence breakdown:**

* Standard stack: \[level] - \[reason]
* Architecture: \[level] - \[reason]
* Pitfalls: \[level] - \[reason]

**Research date:** \[date]
**Valid until:** \[estimate - 30 days for stable, 7 for fast-moving]

````

<Warning>
**CRITICAL:** If CONTEXT.md exists, `## User Constraints` MUST be the FIRST content section in RESEARCH.md.
</Warning>

## Execution Flow

<Steps>
  <Step title="Receive Scope and Load Context">
    Orchestrator provides: phase number/name, description/goal, requirements, constraints, output path
    
    Load phase context using init command, read CONTEXT.md if exists, read config.json for nyquist_validation setting
  </Step>
  <Step title="Identify Research Domains">
    Based on phase description:
    - **Core Technology:** Primary framework, current version, standard setup
    - **Ecosystem/Stack:** Paired libraries, "blessed" stack, helpers
    - **Patterns:** Expert structure, design patterns, recommended organization
    - **Pitfalls:** Common beginner mistakes, gotchas, rewrite-causing errors
    - **Don't Hand-Roll:** Existing solutions for deceptively complex problems
  </Step>
  <Step title="Execute Research Protocol">
    For each domain: Context7 first → Official docs → WebSearch → Cross-verify
    
    Document findings with confidence levels as you go
  </Step>
  <Step title="Validation Architecture Research">
    **Skip if** workflow.nyquist_validation is explicitly false
    
    - Detect test infrastructure
    - Map requirements to tests
    - Identify Wave 0 gaps
  </Step>
  <Step title="Quality Check">
    - [ ] All domains investigated
    - [ ] Negative claims verified
    - [ ] Multiple sources for critical claims
    - [ ] Confidence levels assigned honestly
    - [ ] "What might I have missed?" review
  </Step>
  <Step title="Write RESEARCH.md">
    **ALWAYS use the Write tool** — never heredoc
    
    If CONTEXT.md exists, FIRST content section MUST be user_constraints section
    
    Write to the phase directory RESEARCH.md file
  </Step>
  <Step title="Commit Research (optional)">
    Use gsd-tools.cjs to commit the research document
  </Step>
  <Step title="Return Structured Result">
    Confirm completion with research summary
  </Step>
</Steps>

## Structured Returns

### Research Complete

```markdown
## RESEARCH COMPLETE

**Phase:** phase_number - phase_name
**Confidence:** [HIGH/MEDIUM/LOW]

### Key Findings
[3-5 bullet points of most important discoveries]

### File Created
`$PHASE_DIR/$PADDED_PHASE-RESEARCH.md`

### Confidence Assessment
| Area | Level | Reason |
|------|-------|--------|
| Standard Stack | [level] | [why] |
| Architecture | [level] | [why] |
| Pitfalls | [level] | [why] |

### Open Questions
[Gaps that couldn't be resolved]

### Ready for Planning
Research complete. Planner can now create PLAN.md files.
````

## Philosophy

### Honest Reporting

* "I couldn't find X" is valuable (now we know to investigate differently)
* "This is LOW confidence" is valuable (flags for validation)
* "Sources contradict" is valuable (surfaces real ambiguity)

**Avoid:** Padding findings, stating unverified claims as facts, hiding uncertainty behind confident language.

### Research is Investigation, Not Confirmation

**Bad research:** Start with hypothesis, find evidence to support it

**Good research:** Gather evidence, form conclusions from evidence

When researching "best library for X": find what the ecosystem actually uses, document tradeoffs honestly, let evidence drive recommendation.

## Source Hierarchy

| Level  | Sources                                                            | Use                        |
| ------ | ------------------------------------------------------------------ | -------------------------- |
| HIGH   | Context7, official docs, official releases                         | State as fact              |
| MEDIUM | WebSearch verified with official source, multiple credible sources | State with attribution     |
| LOW    | WebSearch only, single source, unverified                          | Flag as needing validation |

Priority: Context7 → Official Docs → Official GitHub → Verified WebSearch → Unverified WebSearch

## Related Agents

<CardGroup cols={2}>
  <Card title="Planner" icon="diagram-project" href="/agents/planner">
    Consumes RESEARCH.md to create plans
  </Card>

  <Card title="Project Researcher" icon="globe" href="/agents/project-researcher">
    Researches entire project ecosystem
  </Card>
</CardGroup>