/plan

name: plan
argument-hint: "[topic]"
description: "Plan future work, investigate before building, research a topic, or compare the alternatives for a choice. Takes optional free text. The skill reads the request, open drafts, accepted canon, branch, and code, then creates only the documents a later reader needs — none for a small fix. Use for 'plan the X redesign', 'create a roadmap', 'plan a new feature', 'plan the onboarding journey', 'investigate X before we plan', 'compare the alternatives for Y', 'REST or a queue? two teams disagree', 'I need market research before we plan', 'we are regulated — trace the requirements'. With no arguments it resumes an open planning draft or offers what to plan next. Not for recording a decision or documenting existing code — use /archcore:document. Not for checking docs against code — use /archcore:review."

/archcore:plan

Plan future work from the project context. Context resolution (`skills/_shared/gate-contract.md`, section Context resolution) records the claims, unknowns, hazards, and authority; the conductor (`skills/_shared/delta-routing.md`) selects the documents a later reader needs; instruments produce them. Vision types are the primary output. Reads cover all three categories: vision supplies intent and resumption targets, knowledge supplies constraints, experience supplies precedent.

When to use

• "Plan a new feature for CSV export" → typically one `spec` and one `plan`
• "Upgrade the HTTP client across three services with a coordinated rollout" → a `plan` alone
• "Plan the notifications platform" → a `prd`, one `spec` per capability, one `plan`
• "Fix the typo in the onboarding copy" → no document; implement directly
• "I need market research before we plan" → acquisition instrument
• "We must trace these requirements for the auditor" → only the requirement levels that obligation names
• "Investigate X before we plan" → `research`; "Compare the alternatives for Y" → `rnd`
• "REST or a queue for SAP? Two teams disagree", with the facts of both options recorded → `rfc`
• `research <topic>` as the first word → the type `research`

**Not plan:**

• Recording a decision → `/archcore:document`
• Documenting existing code → `/archcore:document`
• Codifying a team standard → `/archcore:document`
• Checking documents against code → `/archcore:review`

Entry

Apply in this order:

| Signal | Action | |---|---| | No arguments, one draft with a state block this command resumes | Resume it at its earliest incomplete gate | | No arguments, several such drafts | Resume rule 10 in `skills/_shared/gate-contract.md` | | No arguments, a clear request in the session or one unfinished plan | Offer a start menu of at most four items, each with the evidence that names it, the recommended item first | | No arguments and no reliable signal | Ask one question — what outcome to plan; a dirty branch alone is not a target | | The first word is a type slug | The explicit type request per `explicit-type-request-wins.adr`; a leading `research` requests the type `research` | | Any other request | Context resolution, then Selection per `skills/_shared/delta-routing.md` | | A decision surfaces at a gate | Record the `adr` through the decision instrument (`skills/_shared/tracks/decision.md`), then return to the open gate |

Research boundary: discovery feeding an `mrd` → `brd` → `urd` requirements chain belongs to acquisition. A request naming a pending decision or a set of candidates to choose between produces `rnd` only when the evidence to choose is missing; any other investigation produces `research`. WHEN the deciding facts are already recorded and the open part is whose weights win — two owners disagree, or the owner has not chosen — the decision instrument records an `rfc`, and no `rnd` is created. A standalone external material is filed through `/archcore:document`. A request proposing a specific target for team review ("let's adopt Y", "draft an RFC for Y") belongs to `/archcore:document`'s decision instrument; a lone "should we switch to Y" with the evidence to choose missing stays here as `rnd`.

Execution

1. Ground

Complete this step before asking the user any question. The research vocabulary probe (`skills/_shared/research-compatibility.md`) runs only under its own condition 1 — a request or type naming `research` or `evidence`, a selection engaging the research instrument, or a grounding result of either type. Add `research` and `evidence` to the planning-moment filter below only when the probe returns `yes`; a topic search without a type filter finds documents of both types on every engine. If this skill has no shell tool, use the probe result the host supplied; if none was supplied, report `needs-vocabulary-probe` with the helper path and stop before the first MCP call that names either type.

The actor-subject probe (`skills/_shared/actor-subject-compatibility.md`) runs under its own condition 1 — a request naming `scenario` or `journey`, a selection engaging the illustrate instrument, or a grounding result of either type — and adds both types to the filter below only when it returns `yes`. The same no-shell rule applies: report `needs-vocabulary-probe` and stop before the first MCP call that names either type.

1. Search `.archcore/` with `mcp__archcore__search_documents` and `mcp__archcore__list_documents` across all three categories. Pass a planning-moment type filter — for example `types=["idea", "prd", "plan", "spec", "rnd", "rfc", "adr", "rule", "task-type", "cpat"]` — and add `"scenario"`, `"journey"` when the actor-subject probe returned `yes` — instead of relying on the global type ranking. Do not exclude a category from reads. 2. WHEN a found document carries `implements`, `depends_on`, or `related` relations, pull the linked documents one hop via `mcp__archcore__list_relations` and `mcp__archcore__get_document`. 3. WHEN a found draft on the topic carries an `archcore:track` state block, resume it per the resume rules i