--- name: drafting-plans description: Turn an approved brief into a step plan where every step is independently verifiable and bound to a concrete local provider with a stated fallback. Use after intent is agreed and capabilities are surveyed, for multi-step or long-running work — 写个计划 / 制定计划 / 拆解一下 / 排一下步骤 / 分几步做. Sizes step granularity by risk rather than uniformly, makes dependencies explicit, and routes work through installed specialist skills instead of improvising. Produces .superclarity//plan.md, which the user approves before any execution begins. Do NOT use before the brief is approved, for single-step tasks, or as a place to reopen scope decisions already settled in the brief. license: MIT metadata: pack: superclarity phase: plan --- # A plan is an execution contract The plan exists so the user can see what you are about to spend their time and money on, and so you cannot quietly drift once you start. It is not documentation. It is the thing you are held to. Answer the user in whatever language they wrote in. ## Preconditions An approved brief, and a capability resolution. Planning without the brief means planning something nobody agreed to. Planning without the resolution means writing steps that may have no way to run. ## Step schema Every step carries these six planning fields. Execution adds and maintains a seventh, `status`, which starts at `pending` — see [the template](templates/plan.md). A step missing `verify` cannot be checked; a step missing `provider` may be unrunnable. ```markdown ### Step 3 — Collect published pricing for the shortlist - capability : web-research - provider : - fallback : fetch tool over user-supplied URLs - verify : pricing captured for all 4 vendors in .superclarity//data/pricing.md - depends : Step 2 - risk : low ``` ## What makes a step good | Requirement | Meaning | | --- | --- | | **Independently verifiable** | It ends in a named artifact or an observable state. "Research the market" cannot be verified; "8 competitor pricing pages saved under `data/`" can. | | **Sized to one capability** | Roughly one or two operations. A step spanning three capabilities is three steps. | | **Explicit dependencies** | If step 4 needs step 3's output, say which output. | | **Provider bound** | Named, with a fallback. `provider: TBD` is not a plan. | | **Risk labelled** | Drives where the checkpoints go. | ## Granularity follows risk, not uniformity Fine-grained where it is expensive, irreversible, or slow. Coarse where it is cheap and reversible — reading files, checking status, and formatting output can share one step. A five-step plan usually beats a fifteen-step plan. Fifteen steps is not thoroughness, it is the same work chopped into pieces nobody can hold in mind, and it produces fifteen status updates the user did not ask for. Do not mechanically copy a profile's skeleton. If the brief already fixes the shortlist, the step that builds one is deleted, not performed. ## Route to specialists If an installed skill covers a step's domain, that skill is the provider. Hand-rolling a substitute for a capability the machine already has is a defect. Two guards: never name a provider that was not confirmed present, and never infer a skill's behaviour from its description alone — load it before you plan real work through it. ## Approval gates go in the plan Gate placement follows the risk tier of what comes next: immediately before the first irreversible step, before anything with real cost, and before any external-facing output. A gate is a step, with `capability: ask-user`, and it states what will happen, what it costs, and what cannot be undone. For a wholly low-risk plan, one gate at the end is enough. Do not put a checkpoint between two file reads. ## Show it before you run it Write [`plan.md`](templates/plan.md) into `.superclarity//` and get approval. If a plan-tracking or todo tool exists, mirror the steps into it so the user sees live status — but the file stays authoritative, because the tool's state dies with the session. Never bury the plan in chat prose; the user cannot track progress against a paragraph. ## Changing the plan Reality diverging from the plan is normal. Silently rerouting is not. When it happens: stop, say what you found, propose two or three revisions with a recommendation, get agreement, rewrite `plan.md`, note the change in the journal. The failure this prevents is the one where a user approves a competitor analysis and receives a brand strategy. ## Worked example Brief: compare four payroll vendors for a decision by the finance lead on the 30th; pricing from published tiers plus quotes the user holds; slide deck preferred. ```markdown ### Step 1 — Confirm shortlist and scoring weights - capability : ask-user - provider : question tool - fallback : ask in prose, end turn - verify : 4 vendors and weighted criteria recorded in brief.md - depends : none - risk : low ### Step 2 — Gather published pricing and feature coverage - capability : web-research - provider : - fallback : fetch tool over user-supplied URLs - verify : one file per vendor under data/, each citing its source URL - depends : Step 1 - risk : low ### Step 3 — Build the weighted comparison matrix - capability : data-transform - provider : python (on PATH) - fallback : hand-built table, 4 rows is tractable - verify : matrix.md scores all 4 vendors on every criterion, no blanks - depends : Step 2 - risk : low ### Step 4 — Review matrix with the user before drafting the recommendation - capability : ask-user - provider : question tool - fallback : ask in prose, end turn - verify : user confirms weights and scores, or states corrections - depends : Step 3 - risk : medium ### Step 5 — Write the recommendation - capability : author-content - provider : you - fallback : none needed - verify : recommendation.md names one vendor and cites the matrix for every reason given - depends : Step 4 - risk : low ``` Five steps, one real gate, and a step where the judgement actually happens rather than a plan that runs from data straight to delivery. The deck was a confirmed capability gap agreed in the brief, so the deliverable is markdown and the gap is carried into the final report as a coverage limit — not discovered at delivery.