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//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.

Phase/topic research — how to implement this well, not just which library to pick.

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

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.

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

Write RESEARCH.md to the resolved path.
End with ## RESEARCH COMPLETE and a 5–10 line summary.

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 ` 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`

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ChristopherAlphonse
• Source: ChristopherAlphonse/calphonse-skills
• License: MIT
• Homepage: https://www.skills.sh/christopheralphonse/calphonse-skills

Install and usage instructions live in the source repository linked above.