plan-mode

name

plan-mode

description

Use this skill when the user asks to plan, design, scope, estimate, or implement a feature, bug fix, refactor, migration, integration, API change, UI change, or other project modification. Enforces a planning gate before editing code — investigate project context, analyze the task, surface ambiguities, contradictions, risks, dependencies, and blockers, ask focused questions, produce an evidence-based step-by-step plan, and implement only after explicit user approval. Not for trivial one-line edits, pure questions about the codebase, or changes the user has already reviewed and approved for direct implementation.

Plan Mode

Prevent premature implementation. Understand → plan → get approval → implement → validate. Do not skip the gate just because a change looks small.

The full protocol — investigation steps, issue classification, the question and plan templates, validation, and special cases — lives in PROTOCOL.md. Read it before planning or implementing.

Default behavior

1. Investigate project context (read-only).
2. Analyze the task: goal, current vs desired behavior, acceptance criteria, scope, edge cases.
3. Classify open issues as ambiguity / contradiction / blocker / risk / assumption.
4. Ask the smallest set of focused questions that unblocks planning.
5. Produce a consistent, evidence-based, step-by-step plan.
6. Wait for explicit approval.
7. Implement only the approved plan.
8. Validate, then report what was and was not checked.

The gate (core rule)

During Plan Mode, do not mutate the project: no editing files, scaffolding, patches, package installs, lockfile updates, migrations, deploys, destructive scripts, or "trying an implementation" to learn the code.

Allowed: read files, search the repo, inspect structure, review tests / docs / configs / API contracts / schemas / migrations, run read-only or non-mutating diagnostic commands, and consult external docs when project context is insufficient.

If a tool or command might mutate state, ask first or avoid it.

Surfacing blockers

Surface ambiguities, contradictions, and blockers before the plan — never bury them inside it. For each, capture: what it is, the evidence, why it matters, whether it blocks implementation, and a proposed default or resolution. If none exist, state No hard blockers found.

Asking questions

Ask only after investigating context, and never for what the repo, tests, docs, or provided context already answer. Group related questions, give each a recommended default, and explain briefly why each answer matters. Avoid open-ended "What should I do?" questions.

Approval

Counts as approval: an explicit "proceed / implement / apply / go ahead / approve", or an edited plan with a clear instruction to continue. Does not count: answering one question, commenting on the plan, asking for more detail or alternatives, or "is this enough?". When approval is ambiguous, ask for a direct confirmation.

If new evidence contradicts the approved plan mid-implementation, pause and return to planning with what changed, the evidence, the impact, and a revised recommendation.

Reference

Full protocol, output templates, and special handling (small tasks, urgent fixes, user-provided plans, partial context): PROTOCOL.md.