researching-phases

<user_command>/kata:research-phase</user_command>

Note: This is a standalone research command. For most workflows, use /kata:plan-phase which integrates research automatically.

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 phase, validate against roadmap, check existing research, gather context, spawn researcher agent, present results.

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

Normalize phase input in step 1 before any directory lookups.

0. Resolve Model Profile

Read model profile for agent spawning:

bash

MODEL_PROFILE=$(cat .planning/config.json 2>/dev/null | grep -o '"model_profile"[[:space:]]*:[[:space:]]*"[^"]*"' | grep -o '"[^"]*"$' | tr -d '"' || echo "balanced")

Default to "balanced" if not set.

Model lookup table:

Agent	quality	balanced	budget
kata-phase-researcher	opus	sonnet	haiku

Store resolved model for use in Task calls below.

1. Normalize and Validate Phase

bash

# Normalize phase number (8 → 08, but preserve decimals like 2.1 → 02.1)
if [[ "$ARGUMENTS" =~ ^[0-9]+$ ]]; then
  PHASE=$(printf "%02d" "$ARGUMENTS")
elif [[ "$ARGUMENTS" =~ ^([0-9]+)\.([0-9]+)$ ]]; then
  PHASE=$(printf "%02d.%s" "${BASH_REMATCH[1]}" "${BASH_REMATCH[2]}")
else
  PHASE="$ARGUMENTS"
fi

grep -A5 "Phase ${PHASE}:" .planning/ROADMAP.md 2>/dev/null

If not found: Error and exit. If found: Extract phase number, name, description.

2. Check Existing Research

bash

ls .planning/phases/${PHASE}-*/RESEARCH.md 2>/dev/null

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

If doesn't exist: Continue.

3. Gather Phase Context

bash

grep -A20 "Phase ${PHASE}:" .planning/ROADMAP.md
cat .planning/REQUIREMENTS.md 2>/dev/null
cat .planning/phases/${PHASE}-*/${PHASE}-CONTEXT.md 2>/dev/null
grep -A30 "### Decisions Made" .planning/STATE.md 2>/dev/null

Present summary with phase description, requirements, prior decisions.

4. Spawn kata-phase-researcher Agent

Research modes: ecosystem (default), feasibility, implementation, comparison.

markdown

<research_type>
Phase Research — investigating HOW to implement a specific phase well.
</research_type>

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

<objective>
Research implementation approach for Phase {phase_number}: {phase_name}
Mode: ecosystem
</objective>

<context>
**Phase description:** {phase_description}
**Requirements:** {requirements_list}
**Prior decisions:** {decisions_if_any}
**Phase context:** {context_md_content}
</context>

<downstream_consumer>
Your RESEARCH.md will be loaded by `/kata:plan-phase` 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."
</downstream_consumer>

<quality_gate>
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 phase-plan expects
</quality_gate>

<output>
Write to: .planning/phases/${PHASE}-{slug}/${PHASE}-RESEARCH.md
</output>

Task(
  prompt=filled_prompt,
  subagent_type="kata-phase-researcher",
  model="{researcher_model}",
  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 INCONCLUSIVE: Show what was attempted, offer: Add context, Try different mode, Manual.

6. Spawn Continuation Agent

markdown

<objective>
Continue research for Phase {phase_number}: {phase_name}
</objective>

<prior_state>
Research file: @.planning/phases/${PHASE}-{slug}/${PHASE}-RESEARCH.md
</prior_state>

<checkpoint_response>
**Type:** {checkpoint_type}
**Response:** {user_response}
</checkpoint_response>

Task(
  prompt=continuation_prompt,
  subagent_type="kata-phase-researcher",
  model="{researcher_model}",
  description="Continue research Phase {phase}"
)

<success_criteria>

Phase validated against roadmap
Existing research checked
kata-phase-researcher spawned with context
Checkpoints handled correctly
User knows next steps </success_criteria>

Search AI Tools

Install this agent skill to your Project

Metadata

SKILL.md

0. Resolve Model Profile

1. Normalize and Validate Phase

2. Check Existing Research

3. Gather Phase Context

4. Spawn kata-phase-researcher Agent

5. Handle Agent Return

6. Spawn Continuation Agent