Explore / Plan Skill

Exact context beats approximation and a written plan beats diving in. Outside plan mode no plan gate fires, so this skill is the gate: run the same steps, write the plan to a scratch file under /tmp/claude, and execute without pausing. Skip this for trivial edits (typos, single-line tweaks) — say so.

1. Explore (read-only)

Understand before changing. Trace the relevant files and data models read-only. Prefer references over descriptions: cite path/to/file.py:42 and read the real code rather than guessing. Pipe real errors in (cat error.log | claude) instead of paraphrasing them. Launch parallel Explore agents when scope is uncertain or spans multiple areas.

Every constraint exploration surfaces gets a verdict, not just a description: work around, or delete toward? A constraint written down without one becomes terrain the plan navigates — which is how a removable duplication survives a planning phase that found it. Answer in one clause per constraint: "two registries → delete toward the packaged one" or "KVM absent on this runner → work around". "Delete toward" is the answer whenever one side is authoritative (a published package, a generated artifact, an upstream already depended on); the cost of the deletion belongs in the plan as work, not as a reason to bridge instead.

2. Plan (written, explicit)

Write an explicit plan: the problem, the approach, the specific files to touch, and the existing helpers/patterns to reuse (search for them — do not invent new code when a utility already exists).

Then name the ONE definition that will own each fact the change touches, before you list the files. For every rule, list, threshold, mapping or vocabulary the plan adds or edits, grep for what already answers it, and write one line per fact: which definition owns it, and what happens to the other copies. A plan step that reads "and also update" is the tell, and so is a diff that edits two files to change one behaviour. Collapse the copies onto one definition in this change, then make the fix at that definition — a deliberate variant is a named sibling beside the owner, never a second copy at a call site. Three functions each deciding which lever a merge state takes is not three edits: it is the divergence the defect came from. .claude/rules/code-style.md owns the rest.

A plan is scaffolding for your own execution, NOT a checkpoint you invent. Per CLAUDE.md's Autonomy rule, once the plan is written execute it immediately — call ExitPlanMode and start (auto mode has no gate to exit: just start). Plan mode is the user's own gate, so add no second one: do not call AskUserQuestion, and do not go idle on a question you can decide. If exploration surfaces a wrong premise or a design fork, pick the sensible default, record it under ## Decisions made, and keep going; the plan file is a live working document you update as you go, never a gate.

NEVER call ExitPlanMode to put a small revision of an existing plan in front of the user — it asks them to re-read and approve a change they did not request. Two things earn a fresh proposal: the user asks for a re-plan, or gives a significantly new task. Everything else — a resequenced step, a narrowed finding, a correction — you edit into the plan file and execute. Only the FIRST exit of a turn the user opened counts as this proposal: a turn resuming an ALREADY-APPROVED plan names the next unblocked item in chat and asks to be released instead of exiting again.

Start convergent setup work in the background while design questions are still open — the one carve-out from "execution starts at ExitPlanMode" above. It covers only work NO outcome of the plan discards: the branch, a tool install, a fetch, an implementation agent for a part the plan has already settled. That work starts during the tail of planning, because a design sub-agent's latency is when it is free. One worked case: while a sub-agent designs a module's structure, the session installs the model checker, and launches the already-settled refactor in a worktree agent. The bound is convergence, and it is what keeps the carve-out from reopening the gate: start only what every open design branch needs, and hold back anything a pending decision could invalidate.

3. Critique and improve (self, before any fresh eyes)

Before handing the plan to a reviewer — or executing it — reread the draft as a hostile reviewer of someone else's work. Hunt for: premises the exploration didn't actually verify, missing files or edge cases, steps that reinvent an existing utility, success criteria you couldn't test, hidden ordering dependencies between steps, and scope creep beyond the request. State each finding in one line, fix the plan, then re-critique the fix (fixes introduce their own gaps). Repeat until a full pass finds nothing, under at most three passes (.claude/rules/development-workflow.md § Self-critique).

4. Review (fresh, unbiased)

Have the plan — and later the diff — reviewed with no implementation bias. Use the peer-review skill, which drives the read-only code-reviewer subagent.

5. Verify (never trust a success claim)

Never accept "it works" without evidence. Before declaring done, produce real output: run the tests, run the app and observe behavior, capture a screenshot for UI changes, or paste the real command output. Type-checks and a green suite prove code correctness, not feature correctness — if you cannot exercise the feature, say so explicitly rather than claiming success.

Examples

Example 1: Multi-file feature

User says, in plan mode: "Plan how we'd add rate limiting to the API."

1. Launches Explore agents to map the request middleware and existing config patterns; reads the real middleware files and cites them.
2. Writes a plan: which middleware to add, where config lives, which existing RedisClient helper to reuse, which tests to add.
3. Self-critiques the plan to a fixed point — first pass finds it never chose where the limiter's counters live; fixes it, and the next pass finds nothing.
4. Runs peer-review on the plan — reviewer notes the plan misses the health-check path; fixes it.
5. After implementing, verifies by hitting the endpoint until throttled and pasting the 429 response.

Example 2: Unfamiliar bug

User says, in plan mode: "Figure out why login intermittently 500s, then fix it."

1. Explores: greps the auth path, reads the session store code, pipes in the real stack trace.
2. Writes a short plan pinpointing the suspected race in token refresh.
3. Implements the fix, then verifies by reproducing the original failure and showing it now passes — not by asserting the change "should" fix it.