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.

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.

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

Be prescriptive, not exploratory. “Use X” not “Consider X or Y.”

What It Does

1. Tool Strategy

Tool Priority:

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

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

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

Enhanced Web Search (Brave API):

If brave_search is enabled:

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

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

// 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]

// 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

Planner

Consumes RESEARCH.md to create plans

Project Researcher

Researches entire project ecosystem