/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`](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`](PROTOCOL.md).