Phase Research

Research how to implement a phase. Spawns orc-phase-researcher agent with phase context.

Use this command when:

• You want to research without planning yet
• You want to re-research after planning is complete
• You need to investigate before deciding if a phase is feasible

Orchestrator role: Parse slug + phase, validate against roadmap, check existing research, gather context, spawn researcher agent, present results.

Why subagent: Research burns context fast (WebSearch queries, source verification). Fresh 200k context for investigation. Main context stays lean for user interaction.

Arguments: $ARGUMENTS = slug phase-num (e.g., my-app 2)

Parse slug and phase number in step 0 before any directory lookups.

0. Initialize Context

Parse $ARGUMENTS into slug and phase number:

• slug = first word
• PHASE = second word

Load project state:

cat .claude/plans/${slug}/STATE.md

Find the phase directory:

ls -d .claude/plans/${slug}/phases/0${PHASE}-*/ 2>/dev/null | head -1

Store as phase_dir. Extract phase_name from the directory name (the part after the number and hyphen).

Check for existing research:

ls ${phase_dir}/RESEARCH.md 2>/dev/null

Store paths for later use:

• state_path = .claude/plans/${slug}/STATE.md
• project_path = .claude/plans/${slug}/PROJECT.md
• roadmap_path = .claude/plans/${slug}/ROADMAP.md
• context_path = ${phase_dir}/CONTEXT.md (if exists)
• research_path = ${phase_dir}/RESEARCH.md

1. Validate Phase

Read ROADMAP.md and find the phase section:

cat .claude/plans/${slug}/ROADMAP.md

Search for ## Phase ${PHASE}: in the ROADMAP.md content. Extract phase number, phase name, and goal from the section.

If phase not found: Error and exit. If phase found: Continue with extracted details.

2. Check Existing Research

If RESEARCH.md exists: Offer: 1) Update research, 2) View existing, 3) Skip. Wait for response.

If doesn't exist: Continue.

3. Gather Phase Context

Use paths from step 0 (do not inline file contents in orchestrator context):

• project_path
• state_path
• roadmap_path
• context_path (if exists)

Present summary with phase description and what files the researcher will load.

4. Spawn orc-phase-researcher Agent

Phase Research -- investigating HOW to implement a specific phase well.

The question is NOT "which library should I use?"

The question is: "What do I not know that I don't know?"

For this phase, discover:
- What's the established architecture pattern?
- What libraries form the standard stack?
- What problems do people commonly hit?
- What's SOTA vs what Claude's training thinks is SOTA?
- What should NOT be hand-rolled?

Research implementation approach for Phase {phase_number}: {phase_name}
Mode: ecosystem

- {project_path} (Project vision and context)
- {context_path} (Phase context from /orc-discuss, if exists)
- {state_path} (Prior project decisions and codebase analysis)
- {roadmap_path} (Full roadmap for cross-phase awareness)

**Phase description:** {phase_description}

Your RESEARCH.md will be loaded by `orc:orc-planner` (phase planner) which uses specific sections:
- `## Standard Stack` -> Plans use these libraries
- `## Architecture Patterns` -> Task structure follows these
- `## 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."

Before declaring complete, verify:
- [ ] All domains investigated (not just some)
- [ ] Negative claims verified with official docs
- [ ] Multiple sources for critical claims
- [ ] Confidence levels assigned honestly
- [ ] Section names match what orc-planner expects

Write to: {phase_dir}/RESEARCH.md

Task(
  prompt=filled_prompt,
  subagent_type="orc:orc-phase-researcher",

  description="Research Phase {phase}"
)

5. Handle Agent Return

## RESEARCH COMPLETE: Display summary, offer: Plan phase, Dig deeper, Review full, Done.

## CHECKPOINT REACHED: Present to user, get response, spawn continuation.

## RESEARCH BLOCKED: Show what was attempted, offer: Add context, Try different mode, Manual.

6. Spawn Continuation Agent

Continue research for Phase {phase_number}: {phase_name}

- {phase_dir}/RESEARCH.md (Existing research)

**Type:** {checkpoint_type}
**Response:** {user_response}

Task(
  prompt=continuation_prompt,
  subagent_type="orc:orc-phase-researcher",

  description="Continue research Phase {phase}"
)

• [ ] Phase validated against roadmap
• [ ] Existing research checked
• [ ] orc-phase-researcher spawned with context
• [ ] Checkpoints handled correctly
• [ ] User knows next steps

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: qGolem
• Source: qGolem/orc
• License: MIT

Install and usage instructions live in the source repository linked above.