| name | research-and-plan |
| argument-hint | [output FILE] <broad goal description> |
| description | Decompose a broad goal into a sequence of executable sub-plans. Researches the domain, identifies sub-problems and dependencies, then produces a meta-plan where each phase delegates to /run-plan. Usage: /research-and-plan [output FILE] <description...> |
/research-and-plan [output FILE] <description...> — Meta-Plan Decomposer
Breaks broad goals into focused sub-plans, each drafted via /draft-plan
and executed via /run-plan. The output is a meta-plan file whose phases
are pure delegation — no drafting happens during execution.
Ultrathink throughout.
Arguments
- output FILE (optional) — meta-plan output path. Default:
plans/<SLUG>_META.md (slug from description).
- description (required) — everything after recognized keywords.
Detection: output + path = explicit file. First token ending .md =
output file (prepend plans/ if no /). Everything else = description.
Escalation from /draft-plan: If the invoking context mentions a
research file at /tmp/draft-plan-research-*.md, read it — that research
feeds Step 1 and avoids redundant exploration.
Step 1 — Decomposition Research
Three focused investigations. If a research file was passed from
/draft-plan, start from it — validate and extend rather than starting
from scratch.
1a. Domain survey — Dispatch Explore agents to map the scope: what the
goal encompasses, what exists already, natural sub-domains, shared
infrastructure needed across sub-problems.
1b. Dependency analysis — Build a dependency graph: which sub-problems
are independent (parallelizable), which are sequential, and whether shared
prerequisites exist (e.g., "generalize the base system" before new features).
1c. Scope sizing — Estimate each sub-problem's size. If a sub-plan
would need 8+ phases, split further. Each must be completable by
/run-plan finish auto in one session. Mark in-scope vs. out-of-scope.
Present the decomposition to the user and wait for confirmation:
Decomposition complete. I identified N sub-problems:
- Sub-problem A — [one-line description] (est. N phases)
- Sub-problem B — [one-line description] (est. M phases, depends on A)
...
Dependency graph: A -> B -> D, A -> C (independent of B)
In scope: [list]. Out of scope: [list].
Approve this decomposition? I'll draft sub-plans for each.
Do NOT proceed until the user confirms. They may reorder, drop, merge,
or add sub-problems.
Step 2 — Draft All Sub-Plans
After user approval, draft each sub-plan by dispatching /draft-plan
agents sequentially. Each runs in its own context and gets full
adversarial review.
For each sub-problem:
- Determine the sub-plan output path:
plans/<SLUG>_<N>.md (or let the
user specify).
- If research from Step 1 was written to a file, pass that path to the
/draft-plan agent so it has the decomposition context.
- Dispatch:
/draft-plan output <path> <sub-problem description>
Staleness notes for dependent sub-plans. Sub-plans that depend on
earlier ones get this in their Dependencies section:
### Dependencies
- Plan A must be complete. **Note:** This plan was drafted before Plan A
was implemented. APIs and data structures referenced here are based on
Plan A's design, not actual code. `/run-plan` may refresh this plan
before execution.
This tells /run-plan to offer a plan refresh (interactive) or
auto-refresh (auto mode) before implementing — ensuring the plan reflects
actual code, not predictions.
Step 3 — Adversarial Review of the Decomposition
One round of review focused on the decomposition itself (not the
individual sub-plans — those already got reviewed by /draft-plan).
Dispatch two agents in parallel:
Reviewer agent
- Are the sub-problem boundaries clean? (No shared work split across plans)
- Is the dependency ordering correct?
- Are there missing sub-problems? (Infrastructure, integration testing,
documentation?)
- Is scope sizing realistic?
Devil's advocate agent
- Wrong split — would a different decomposition be simpler?
- Hidden coupling — do sub-plans share assumptions that will break if
one changes?
- Missing glue — who integrates the sub-plans? Is there a final
integration phase?
- Deferred complexity — is the hardest part buried in the last sub-plan?
Address every finding: fix the decomposition or justify why it's not a
problem. If the decomposition changes, update affected sub-plans.
Step 4 — Write the Meta-Plan
After all sub-plans are drafted and the decomposition is reviewed, write
the meta-plan. Every phase is pure delegation — /run-plan executes
sub-plans, no /draft-plan during execution.
Meta-plan template
# Meta-Plan: <Title>
## Overview
[What this meta-plan accomplishes and the decomposition rationale]
## Decomposition
[Sub-problems identified, dependency graph, scope rationale]
## Sub-Plans
| Plan | Phases | Dependencies | Notes |
|------|--------|--------------|-------|
| [SUB_PLAN_A.md](SUB_PLAN_A.md) | N | None | |
| [SUB_PLAN_B.md](SUB_PLAN_B.md) | M | A | May need refresh after A |
## Progress Tracker
| Phase | Status | Commit | Notes |
|-------|--------|--------|-------|
| 1 — Implement: <sub-problem A> | ⬚ | | |
| 2 — Implement: <sub-problem B> | ⬚ | | |
## Phase N — Implement: <Sub-problem X>
### Goal
Execute the plan for <sub-problem X>.
### Execution: delegate /run-plan plans/<SUB_PLAN_X>.md finish auto
### Acceptance Criteria
- [ ] All phases in the sub-plan are marked Done
- [ ] All tests pass on main after landing
- [ ] Plan report exists with verification results
### Dependencies
[List prerequisite phases. Dependent sub-plans may auto-refresh.]
## Plan Quality
**Drafting process:** /research-and-plan with decomposition review
**Sub-plans:** Each drafted via /draft-plan with adversarial review
**Decomposition review:** 1 round (reviewer + devil's advocate)
Repeat the Phase N template for each sub-problem. First phase has
Dependencies: None. Dependent phases list their prerequisites and note
that the sub-plan may auto-refresh to reflect actual implementation.
Finalization
- Write the meta-plan to the output path.
- Update
plans/PLAN_INDEX.md if it exists (add a row to "Ready to Run").
If it doesn't exist, suggest /plans rebuild.
- Present the result:
Meta-plan written to plans/<FILE>.md with N sub-plans.
Sub-plans: [list with paths]
Execute with: /run-plan plans/<FILE>.md
Or with scheduling: /run-plan plans/<FILE>.md auto every 4h now
Key Rules
- Pure delegation in the meta-plan. Every phase uses
### Execution: delegate /run-plan. No delegate /draft-plan — all
drafting happens upfront in Step 2.
- User confirms the decomposition. Step 1 ends with a checkpoint.
Do not draft sub-plans until the user approves the split.
- Staleness notes on dependent sub-plans. Sub-plans drafted before
their dependencies are implemented get explicit warnings so
/run-plan
knows to refresh.
- Adversarial review targets the decomposition. Individual sub-plans
get their own review via
/draft-plan. Step 3 reviews the split itself.
- Respect constraints. Check CLAUDE.md for any project-specific
constraints that apply to every sub-plan.
- Each sub-plan must be session-completable. If a sub-plan needs 8+
phases, split it further.
