Plan

Plan

Purpose

Turn the request and repository evidence into the smallest decision-ready spec and execution map that can verify the requested outcome. Plan to the level warranted by current scope and risk; do not add ceremony or speculative architecture.

Workspace protocol

Read references/workspaces.md once per agent task before selecting or creating workflow artifacts; reuse it unless repository scope or task authority changes. This skill owns only the task-specific behavior below.

Inputs

• User goal, constraints, and expected behavior
• Applicable AGENTS.md, current code, tests, docs, issues, and runtime evidence
• The selected work item's spec, plan, and decisions when durable state is active

Outputs

• A requirement snapshot separating confirmed intent, observed behavior, inferences, and blocking questions
• A decision-ready spec and smallest coherent execution map with an Acceptance Contract of testable criteria
• A compact Behavior-to-Proof map for multi-criterion or material-risk work
• For approved durable work, updated spec.md and plan.md in the selected work-item directory
• A short summary of assumptions and human decisions needed

Rules

• Inspect the real code path before decomposing implementation work.
• Summarize the affected user or operator, desired observable behavior, must-have and must-not behavior, constraints, and success signals; separate confirmed intent, observed current behavior, inferences, and unknowns.
• Ask only when an unresolved choice changes user-visible behavior, acceptance criteria, scope, compatibility, or irreversible risk. Ask one to three highest-leverage questions per round; never ask for facts safely discoverable from the repository.
• Do not call a spec decision-ready or finalize its Acceptance Contract while such a blocking choice remains. Use brainstorm when the product or technical direction is still genuinely open.
• State reversible low-impact assumptions and proceed when they cannot materially change the contract.
• Default to the smallest sufficient change that satisfies confirmed outcomes and constraints; prefer existing paths, patterns, and components before adding new ones.
• Every proposed component and plan item must map to a current requirement, acceptance criterion, repository fact, or material risk. Remove work justified only by generic flexibility, hypothetical scale, or unspecified future reuse.
• For a small reversible change, prefer one to three outcome-based steps and a direct proof path; exceed that only when repository evidence or material risk requires separate work.
• Define an Acceptance Contract with stable AC-<number> identifiers for every user-visible or externally observable outcome.
• For each acceptance criterion, state the observable outcome, verification boundary, and expected evidence; include at least one verification method.
• For multi-criterion or material-risk work, present a compact Behavior-to-Proof map linking each acceptance ID to its planned proof; omit the table for a trivial single outcome.
• Link each execution-plan outcome to the affected acceptance IDs when applicable; do not invent acceptance criteria for purely enabling internal tasks.
• Before finalizing multi-step work, assess whether acceptance outcomes, affected components, cross-cutting risks, and unresolved decisions fit one independently verifiable change. If not, propose the smallest coherent slices and ask once for direction before creating artifacts for them.
• Add negative, compatibility, rollout, or rollback criteria only when material to the risk.
• Keep optional enhancements and future possibilities out of the current plan. Mention a deferred item only when useful, label it Not now, and state the concrete evidence or threshold that would justify revisiting it.
• Do not add a new abstraction, dependency, service, data store, migration, feature flag, observability stack, or rollout mechanism unless the current acceptance contract, repository evidence, or material risk requires it.
• Keep work items outcome-based and independently verifiable; avoid file-by-file pseudo-instructions.
• When an approved plan item will be delegated, make its packet self-contained enough to execute without hidden conversation context: include its outcome, accepted decisions, bounded scope, relevant acceptance IDs, required proof, and escalation conditions.
• Do not edit production code while the request is planning-only.
• Re-plan when new evidence invalidates a premise rather than defending the old plan.

Decision-log updates

Record scope interpretations, contract choices, rejected approaches with non-obvious tradeoffs, and material re-plans. Link each entry to the affected plan item. When durable state is approved, append the decision to the selected work item's decisions.md; otherwise include it in the final response.

Escalate to the human

Escalate when competing interpretations change user-visible behavior, a required system or owner is outside scope, risk cannot be bounded, or the plan requires destructive operations, production access, significant spend, or a product decision. Otherwise state reasonable assumptions and proceed.