# Plan Research

> Research how to implement a phase or planning topic before detailed planning. Produces RESEARCH.md for downstream plan and review skills.

- Skill: `christopheralphonse/plan-research` (Agent Skill)
- Install (CLI): `npx skillmds@latest add christopheralphonse/plan-research`
- Raw SKILL.md: https://api.skillmd.com/api/skills/christopheralphonse/plan-research/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Research & Search
- Author: ChristopherAlphonse (https://skillmd.com/u/christopheralphonse)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/christopheralphonse/plan-research

---


# Plan Research

Research implementation approach **before** planning or coding. Produces `RESEARCH.md` (or an equivalent research artifact) that downstream planning skills consume.

## Guardrails

- Start by narrowing the research question and success criteria.
- Prefer primary sources and local code evidence over broad surveys.
- Label uncertainty, version risk, and assumptions.
- Do not produce implementation plans or code unless explicitly asked.

## When to use

- Research without planning yet
- Re-research after planning is complete
- Investigate feasibility before committing to a phase
- Ad-hoc research for a topic not yet tied to a roadmap phase (write under `.planning/research/`)

For full planning flows, use `/plan` instead.

## Process

### 1. Resolve scope

- **Phase number** (e.g. `3`, `2.1`): locate `.planning/phases/*/` matching the phase; read `ROADMAP.md`, phase `CONTEXT.md`, `REQUIREMENTS.md`, and `.planning/PROJECT.md` if present.
- **Topic string** (e.g. "local build and test workflow"): treat as a research brief; write to `.planning/research/<slug>/RESEARCH.md` (create directories as needed).

If neither a valid phase nor a clear topic is provided, ask one clarifying question.

### 2. Check existing research

If `RESEARCH.md` already exists at the target path, offer:

1. Update research
2. View existing (print path + summary; do not overwrite)
3. Skip

Wait for the user's choice unless they passed an explicit force-refresh intent.

### 3. Gather context (paths only in orchestrator)

Load by reference; do not paste large files into the orchestrator message:

- Requirements and project state under `.planning/`
- Phase `CONTEXT.md` when researching a phase
- Relevant codebase areas (build config, CI, package manifests, etc.)

Summarize what the researcher will read before spawning.

### 4. Spawn researcher subagent

Use `Task` with `subagent_type="explore"` or `generalPurpose` and a fresh context budget. Research burns tokens fast (docs, web, verification).

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

```markdown
<research_type>
Phase/topic research — how to implement this well, not just which library to pick.
</research_type>

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

Discover:
- Established architecture patterns for this domain
- Standard stack and versions
- Common pitfalls and failure modes
- SOTA vs training-data assumptions
- What must NOT be hand-rolled
</key_insight>

<downstream_consumer>
RESEARCH.md sections should be prescriptive where planning will consume them:
- ## Standard Stack
- ## Architecture Patterns
- ## Don't Hand-Roll
- ## Common Pitfalls
- ## Code Examples (when useful)

Use "Use X" not "Consider X or Y" for decisions planning must take.
</downstream_consumer>

<quality_gate>
- [ ] All relevant domains investigated
- [ ] Critical claims verified against official docs
- [ ] Confidence levels stated honestly
- [ ] Section names match what plan and review skills expect
</quality_gate>

<output>
Write RESEARCH.md to the resolved path.
End with ## RESEARCH COMPLETE and a 5–10 line summary.
</output>
```

### 5. Handle subagent return

| Marker | Action |
| --- | --- |
| `## RESEARCH COMPLETE` | Show summary; offer `/plan`, dig deeper, review full, done |
| `## CHECKPOINT REACHED` | Present checkpoint; get user response; spawn continuation with prior `RESEARCH.md` |
| `## RESEARCH INCONCLUSIVE` | Show attempts; offer more context, different mode, or manual follow-up |

### 6. Continuation

If the user continues after a checkpoint, spawn again with `<files_to_read>` pointing at the existing `RESEARCH.md` and the user's checkpoint response.

## Operating rules

- Research-only: do not write `PLAN.md` or implementation code unless the user explicitly asks.
- Prefer subagents for investigation; keep the orchestrator lean.
- Durable outputs live under `.planning/` only.

## Success criteria

- [ ] Scope resolved (phase or topic + output path)
- [ ] Existing research handled (prompt, view, or skip)
- [ ] Researcher spawned with correct context
- [ ] `RESEARCH.md` written or viewed as requested
- [ ] User knows next step (plan, deeper research, or stop)

---

> **Install:** ``npx skills add ChristopherAlphonse/calphonse-skills --skill plan-research``