paul:research-phase

When to use: Before planning a phase when there are technical unknowns that need investigation.

Distinction from /paul:research:

• /paul:research <topic>: User knows what to research
• /paul:research-phase <N>: Claude identifies what needs researching

Subagent orchestration: Spawns multiple research agents in parallel for independent unknowns.

<execution_context> @/.claude/paul-framework/workflows/research.md @/.claude/paul-framework/references/subagent-criteria.md </execution_context>

@.paul/PROJECT.md @.paul/STATE.md @.paul/ROADMAP.md

If argument missing:

Error: Phase number required.

Usage: /paul:research-phase <phase-number>
Example: /paul:research-phase 10

Exit workflow.

1. Validate phase exists in ROADMAP.md
2. Extract phase scope, goals, and description

If phase not found:

Error: Phase {N} not found in roadmap.

Available phases:
[list incomplete phases from roadmap]

Exit workflow.

1. Read ROADMAP.md phase description
2. Read PROJECT.md for context
3. Check for existing CONTEXT.md in phase directory

Identify unknowns in these categories:

Category	Examples
Codebase	"How does X work in this project?", patterns to follow
Web/Docs	Library features, API patterns, best practices
Comparison	"Should we use X or Y?", tradeoff analysis
Architecture	Design patterns, integration approaches

Classification logic:

• Codebase unknowns → Explore agent
• Web/docs unknowns → general-purpose agent

Filter for substantial unknowns:

• Only include items that need 15+ min research
• Trivial lookups handled in main session
• Max 3 parallel research agents (token efficiency)

Present findings:

════════════════════════════════════════
PHASE UNKNOWNS ANALYSIS
════════════════════════════════════════

Phase: {N} — {phase_name}

Identified unknowns:
1. {unknown_1} [{codebase|web}]
2. {unknown_2} [{codebase|web}]
3. {unknown_3} [{codebase|web}]

{If more than 3:}
Additional unknowns (will research after initial batch):
4. {unknown_4}
5. {unknown_5}

────────────────────────────────────────
Proceed with research? [yes/no/modify list]
────────────────────────────────────────

Wait for user confirmation.

Criterion	Check
Task Independence	Each unknown is self-contained ✓
Clear Scope	Unknown defines research question ✓
Parallel Value	Multiple agents run simultaneously ✓
Complexity Sweet Spot	Each 15-30 min expected ✓
Token Efficiency	Batch spawn, consolidated return ✓
State Compatibility	No blocking checkpoints ✓

Spawn agents in parallel:

Use multiple Task tool calls in single message:

Task 1 (Codebase unknowns):
- subagent_type: Explore
- description: "Research: {unknown}"
- run_in_background: true (if multiple)
- prompt: [research prompt]

Task 2 (Web unknowns):
- subagent_type: general-purpose
- description: "Research: {unknown}"
- run_in_background: true (if multiple)
- prompt: [research prompt]

Display:

Spawning {N} research agents...

Agent 1: {unknown_1} (Explore)
Agent 2: {unknown_2} (general-purpose)
Agent 3: {unknown_3} (Explore)

Researching in parallel. This may take a few minutes...

1. Create research directory for phase:

   mkdir -p .paul/phases/{NN}-{name}/research
   

2. Save individual findings:

   • .paul/phases/{NN}-{name}/research/{unknown-slug}.md

3. Create consolidated RESEARCH.md:

   • .paul/phases/{NN}-{name}/RESEARCH.md
   • Summarizes all findings
   • Links to individual research files