Plan

Plan

Create a grounded, decision-complete plan before complex work.

Scope

• Use this skill ONLY when the user explicitly asks to plan — they request a plan, design, approach, rollout or migration strategy, or PR breakdown, or invoke the plan skill directly (/skill plan).
• Do NOT use this skill for ordinary implement, build, fix, debug, or refactor requests. When asked to make a code change, do the work directly without planning first — even when the task is complex. Task complexity alone is not a trigger; the explicit planning request is.
• Once planning, adapt to the plan TYPE the request implies — implementation, design, debugging, rollout or migration, eval or research, or PR split (see Plan Shape). The plan type is a separate axis from the trigger: a debugging, implementation, or evaluation plan type is never itself a reason to invoke the skill on an ordinary coding task.
• Skip this skill for simple one-step edits, obvious bug fixes, formatting, copy changes, and direct questions that can be answered without planning.
• Treat this as planning guidance, not a host-enforced mode. Do not call this a mode in user-facing text or claim that the host is blocking write tools, commands, edits, or approvals for you.
• Do not write a plan file unless the user explicitly asks for persistence or a governing workspace workflow requires a named plan artifact. You may write at most one such markdown file.
• Do not edit code, apply patches, format, generate code, commit, push, open PRs, or run commands whose purpose is to carry out the implementation while planning.
• You may run non-mutating discovery: read and search files, inspect docs and specs, check git status, run dry-run commands, and run tests or builds only when they do not change tracked files.
• Resolve facts that can be discovered locally before asking the user.
• Ask only for product preferences or tradeoffs that cannot be discovered from the workspace.

Research Before Drafting

For an explicit plan, follow these steps in order. Do not write plan prose or a plan file until the applicable research in steps 1-5 is complete:

1. Map the decisions. Identify the material choices the plan must make and the information needed for each. Separate workspace facts, external facts, user preferences, and assumptions.
2. Research workspace facts. Establish current behavior, constraints, reuse options, and validation paths with targeted reads of applicable instructions, decisions, owning code or docs, callers, tests, configuration, and existing utilities. Treat a prior plan as navigation, not evidence; verify the sources it cites.
3. Ask only when necessary. A user requests a collaborative checkpoint only when they explicitly ask you to work through unresolved plan or design choices with them before the plan is drafted. Merely requesting a plan, design, review, or later go-ahead does not qualify. For that checkpoint, after researching discoverable facts, ask a remaining material user-owned product preference or tradeoff before drafting when it would otherwise appear as an open question at the end of the plan. For this checkpoint only, that overrides the reversible-default guidance below; all question-shaping and unavailable-tool rules still apply. Otherwise follow the ordinary rule below. Before calling request_user_input, research any factual unknown that could eliminate the question; this may include bounded, preference-independent external research. Do not ask merely because scope, platform, or experience is unspecified. Use request_user_input only when a remaining user-owned preference cannot be resolved from the request, workspace, or research and its answer would materially change the research or recommendation, or avoid substantial rework. If a reasonable, reversible default lets planning continue safely, state it as an assumption and continue instead of asking. Phrase necessary questions as desired outcomes or experience, not named methods, libraries, engines, or frameworks: ask "arcade feel or realistic simulation," not "custom physics or Matter.js." Research and recommend the technical implementation yourself. When input is necessary, ask only one necessary question per turn. Do not set auto_resolution_ms for a necessary question; wait for the answer. If a choice can safely take a reversible default, do not open a prompt: state the assumption in the plan instead. If the tool is unavailable, carry the missing choice as an open question and keep dependent recommendations conditional.
4. Research external facts when they matter. A substantial greenfield or unfamiliar plan must use available external research capabilities and inspect relevant authoritative primary sources for key technical decisions about current domain practice, libraries, engines, APIs, platforms, or standards before recommending an approach. If input is necessary, wait for its response before branch-specific external research. Research the path selected by the user's preferences; a preference constrains the research, but does not replace it. Source discovery is not source inspection. Search summaries, indexes, candidate lists, and similar discovery artifacts only locate sources; they do not complete research. Before a key external recommendation, inspect the underlying content of an authoritative or primary source. Every material external claim or decision must trace to source content inspected during this run. A source counts as inspected only when its underlying content was successfully returned and non-empty. A failed, redirected, not-found, empty, or discovery-only result does not qualify. If underlying content is unavailable, record the evidence gap and keep the recommendation conditional. An empty workspace, discovery summaries, and model memory are not sufficient evidence. Skip external research when binding workspace evidence already answers the decision. Cite only source content inspected during this run, keep claims within what those sources support, and prefer an official primary source when sources conflict. Use roundup, comparison, or tutorial pages only to discover candidates, never as the authority for a final key decision; verify candidates against official documentation, standards, or project repositories. Do not turn a source into a stronger claim than it makes or invent versions, sizes, performance thresholds, or retry behavior.
5. Close delegated research. Immediately before writing plan prose or a plan file, inspect every research child you spawned. A wait call timing out is not a terminal child state. While any child remains pending, check its status and keep waiting. Receive every terminal result and incorporate relevant findings before drafting; record failed, cancelled, or unavailable research as a gap. A plan-directory creation or plan-file write while a research child is nonterminal is forbidden. If you cancel a child, wait for terminal cancellation and record its result or evidence gap before drafting.
6. Synthesize, then draft. Immediately before drafting, build a private decision-evidence map. Every external candidate that will appear anywhere in the plan as a choice, alternative, fallback, risk, or rejection must map to successfully inspected authoritative content. Remove any candidate without that evidence; discovery pages cannot fill the map. Store the exact inspected URL in that map; do not reconstruct, abbreviate, or infer a citation. Only then recommend the approach. Keep assumptions and unresolved questions explicit, and make the Key Decisions, Work Plan, and Validation Plan agree with the user's constraints and the gathered facts.

Stop researching when the decision map is supported well enough to plan. Use direct tools for bounded research; delegate only when parallel work materially improves the evidence. If the user explicitly asks to stop or shorten research, follow the latest instruction and label the remaining gaps.

Quality Bar

A plan is ready only when it is:

• Grounded: cite the user goal, current facts, docs, nearby code, tests, commands, logs, specs, issues, or PRs that shaped the plan when those sources exist. Mark guesses as assumptions.
• Decision-complete: name the key choices, the recommended choice, and why reasonable alternatives were rejected when they matter.
• Purpose-fit: choose the plan type that matches the work: implementation, design, debug, migration/rollout, eval/research, or review/PR split.
• Executable: turn the approach into ordered work units with clear dependencies, owners or surfaces, and no unrelated cleanup.
• Verifiable: each work unit has a focused validation command or real manual check. Include E2E, black-box, or release-binary checks when the surface needs them.
• Scope-safe: state non-goals, risks, rollback, and compatibility impact when they affect the implementation.
• Question-minimal: include open questions only when local discovery cannot answer them.
• Not just a task list: explain the context, recommended approach, and evidence path clearly enough that another person can critique the plan before execution.

Explicit File Output

Deliver the plan inline by default. Do not write a plan file unless the user explicitly asks to save it or a governing workspace workflow requires a named plan artifact. Complexity, possible reuse, or a possible later handoff is not permission to write.

When persistence is authorized:

• If the user gives a path or the governing workflow names one, use that path.
• If the workspace has an established durable plan location, follow it. Prefer, in order: an active specs/<feature>/plan.md for Spec Kit work, an existing docs or project plan convention such as docs/plans/, or a documented plan directory.
• If saving and no stronger convention exists, save to .agents/plans/YYYY-MM-DD-<slug>.md.
• Create parent directories as needed.
• You may update an active specs/<feature>/plan.md, an existing user-specified plan path, or a plan file you saved this session. Never overwrite any other existing file unless the user explicitly asks. When creating a new dated file and the chosen file exists, add a short numeric suffix.
• Do not use /tmp for the final plan. Temporary scratch is not a durable user artifact.

User-Visible Delivery

Start the final reply with this exact sentence on one line so the next action stays visible even when a long plan is collapsed:

This is a plan, not a special mode; I haven’t started implementation. Reply go to execute this plan, or tell me what to change.

Then present the complete reviewable Markdown plan exactly once in that normal user-visible assistant reply. Saving or rereading a plan file is not presenting it.

Use one canonical Markdown plan body. Keep it concise, but do not impose a fixed character or token limit or truncate material decisions, work phases, validation steps, risks, or open questions. Compress supporting evidence into concise citations, never the material decisions, phases, validation, risks, or open questions. If you save a plan file, its content must be exactly the canonical body. Copy the canonical body verbatim into the normal assistant reply. Choose that body before writing the file; never put a longer or different plan in the file. Save only when you can reproduce the entire exact body in the next normal reply. If you cannot, skip the file and deliver the complete plan inline. Do not create two independently expanded versions of the plan. If you save the plan, put its path after the visible plan. The saved file is supplementary and never replaces the normal assistant reply. When external research informs the plan, include a compact ## Sources section containing only exact URLs from successful non-empty underlying-content results. Each material external decision must cite one of those URLs.