phase-research

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.

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.