Claude-Code-Workflow/.claude/skills/team-roadmap-dev/roles/planner/commands/research.md

Command: research

Gather context for a phase before creating execution plans. Explores the codebase, reads requirements from roadmap, and produces a structured context.md file.

Purpose

Build a comprehensive understanding of the phase's scope by combining roadmap requirements, prior phase outputs, and codebase analysis. The resulting context.md is the sole input for the create-plans command.

When to Use

• Phase 2 of planner execution (after task discovery, before plan creation)
• Called once per PLAN-* task (including gap closure iterations)

Strategy

Subagent delegation (cli-explore-agent) for codebase exploration, supplemented by optional Gemini CLI for deep analysis when depth warrants it. Planner does NOT explore the codebase directly -- it delegates.

Parameters

Parameter	Source	Description
sessionFolder	From PLAN-* task description	Session artifact directory
phaseNumber	From PLAN-* task description	Phase to research (1-based)
depth	From config.json or task description	"quick" / "standard" / "comprehensive"

Execution Steps

Step 1: Read Roadmap and Extract Phase Requirements

const roadmap = Read(`${sessionFolder}/roadmap.md`)
const config = JSON.parse(Read(`${sessionFolder}/config.json`))
const depth = config.depth || "standard"

// Parse phase section from roadmap
// Extract: goal, requirements (REQ-IDs), success criteria
const phaseSection = extractPhaseSection(roadmap, phaseNumber)
const phaseGoal = phaseSection.goal
const requirements = phaseSection.requirements    // [{id: "REQ-101", desc: "..."}, ...]
const successCriteria = phaseSection.successCriteria  // ["testable behavior 1", ...]

Step 2: Read Prior Phase Context (if applicable)

const priorContext = []

if (phaseNumber > 1) {
  // Load summaries from previous phases for dependency context
  for (let p = 1; p < phaseNumber; p++) {
    try {
      const summary = Glob(`${sessionFolder}/phase-${p}/summary-*.md`)
      for (const summaryFile of summary) {
        priorContext.push({
          phase: p,
          file: summaryFile,
          content: Read(summaryFile)
        })
      }
    } catch {
      // Prior phase may not have summaries yet (first phase)
    }

    // Also load verification results for dependency awareness
    try {
      const verification = Read(`${sessionFolder}/phase-${p}/verification.md`)
      priorContext.push({
        phase: p,
        file: `${sessionFolder}/phase-${p}/verification.md`,
        content: verification
      })
    } catch {}
  }
}

// For gap closure: load the verification that triggered re-planning
const isGapClosure = planTaskDescription.includes("Gap closure")
let gapContext = null
if (isGapClosure) {
  gapContext = Read(`${sessionFolder}/phase-${phaseNumber}/verification.md`)
}

Step 3: Codebase Exploration via cli-explore-agent

// Build exploration query from requirements
const explorationQuery = requirements.map(r => r.desc).join('; ')

const exploreResult = Task({
  subagent_type: "cli-explore-agent",
  run_in_background: false,
  description: `Explore codebase for phase ${phaseNumber} requirements`,
  prompt: `Explore this codebase to gather context for the following requirements:

## Phase Goal
${phaseGoal}

## Requirements
${requirements.map(r => `- ${r.id}: ${r.desc}`).join('\n')}

## Success Criteria
${successCriteria.map(c => `- ${c}`).join('\n')}

## What to Find
1. Files that will need modification to satisfy these requirements
2. Existing patterns and conventions relevant to this work
3. Dependencies and integration points
4. Test patterns used in this project
5. Configuration or schema files that may need updates

## Output Format
Provide a structured summary:
- **Relevant Files**: List of files with brief description of relevance
- **Patterns Found**: Coding patterns, naming conventions, architecture patterns
- **Dependencies**: Internal and external dependencies that affect this work
- **Test Infrastructure**: Test framework, test file locations, test patterns
- **Risks**: Potential issues or complications discovered`
})

Step 4: Optional Deep Analysis via Gemini CLI

// Only for comprehensive depth or complex phases
if (depth === "comprehensive") {
  const analysisResult = Bash({
    command: `ccw cli -p "PURPOSE: Deep codebase analysis for implementation planning. Phase goal: ${phaseGoal}
TASK: \
  - Analyze module boundaries and coupling for affected files \
  - Identify shared utilities and helpers that can be reused \
  - Map data flow through affected components \
  - Assess test coverage gaps in affected areas \
  - Identify backward compatibility concerns
MODE: analysis
CONTEXT: @**/* | Memory: Requirements: ${requirements.map(r => r.desc).join(', ')}
EXPECTED: Structured analysis with: module map, reuse opportunities, data flow diagram, test gaps, compatibility risks
CONSTRAINTS: Focus on files relevant to phase ${phaseNumber} requirements" \
    --tool gemini --mode analysis --rule analysis-analyze-code-patterns`,
    run_in_background: false,
    timeout: 300000
  })

  // Store deep analysis result for context.md
}

Step 5: Write context.md

Bash(`mkdir -p "${sessionFolder}/phase-${phaseNumber}"`)

const contextContent = `# Phase ${phaseNumber} Context

Generated: ${new Date().toISOString().slice(0, 19)}
Session: ${sessionFolder}
Depth: ${depth}

## Phase Goal

${phaseGoal}

## Requirements

${requirements.map(r => `- **${r.id}**: ${r.desc}`).join('\n')}

## Success Criteria

${successCriteria.map(c => `- [ ] ${c}`).join('\n')}

## Prior Phase Dependencies

${priorContext.length > 0
  ? priorContext.map(p => `### Phase ${p.phase}\n- Source: ${p.file}\n- Key outputs: ${extractKeyOutputs(p.content)}`).join('\n\n')
  : 'None (this is the first phase)'}

${isGapClosure ? `## Gap Closure Context\n\nThis is a gap closure iteration. Gaps from previous verification:\n${gapContext}` : ''}

## Relevant Files

${exploreResult.relevantFiles.map(f => `- \`${f.path}\`: ${f.description}`).join('\n')}

## Patterns Identified

${exploreResult.patterns.map(p => `- **${p.name}**: ${p.description}`).join('\n')}

## Dependencies

${exploreResult.dependencies.map(d => `- ${d}`).join('\n')}

## Test Infrastructure

${exploreResult.testInfo || 'Not analyzed (quick depth)'}

${depth === "comprehensive" && analysisResult ? `## Deep Analysis\n\n${analysisResult}` : ''}

## Questions / Risks

${exploreResult.risks.map(r => `- ${r}`).join('\n')}
`

Write(`${sessionFolder}/phase-${phaseNumber}/context.md`, contextContent)

Output

Artifact	Path	Description
context.md	{sessionFolder}/phase-{N}/context.md	Structured phase context for plan creation

Error Handling

Scenario	Resolution
roadmap.md not found	Error to coordinator via message bus
cli-explore-agent fails	Retry once. Fallback: use ACE search_context directly
Gemini CLI fails	Skip deep analysis section, proceed with basic context
Prior phase summaries missing	Log warning, proceed without dependency context
Phase section not found in roadmap	Error to coordinator -- phase number may be invalid