| name | explore-plan |
| description | Drives the Explore -> Plan -> Critique -> Review -> Verify discipline for non-trivial, multi-file work before any code is written. Activate when the user asks to "plan this", "scope this out", "figure out how to do X", "explore the codebase first", or is starting a change that touches several files or an unfamiliar area. Enforces a self-critiqued written plan and real verification instead of trusting a success claim.
|
Explore / Plan Skill
For non-trivial work, exact context beats approximation and a written plan beats diving in. This
skill codifies the five-phase loop. Skip it for trivial edits (typos, single-line tweaks)—say so.
1. Explore (read-only)
Understand before changing. Use plan mode for read-only tracing of the relevant files and data
models. 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.
2. Plan (written, explicit)
Before multi-file changes, 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). A written plan is reviewable and catches wrong premises before they cost edits.
A plan is scaffolding for your own execution, NOT a checkpoint to hand back and wait on. Per
CLAUDE.md's Autonomy rule ("DO NOT STOP TO ASK"): once the plan is written, execute it
immediately — do not stop, do not call ExitPlanMode/AskUserQuestion, do not hand the user an
unapproved plan and go idle. 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. The user launched work to come back to
results, not to a plan prompt.
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, capped at ~3 passes—the same fixed-point discipline as CLAUDE.md's
Self-Critique Loop, applied to the plan instead of the code. A plan that hasn't survived its own
critique wastes the reviewer's pass on defects you could have caught yourself.
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. A reviewer that did not write the plan
catches assumptions the author cannot see.
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: “Plan how we’d add rate limiting to the API.”
- Launches
Explore agents to map the request middleware and existing config patterns; reads the
real middleware files and cites them.
- Writes a plan: which middleware to add, where config lives, which existing
RedisClient helper to
reuse, which tests to add.
- 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.
- Runs
peer-review on the plan—reviewer notes the plan misses the health-check path; fixes it.
- After implementing, verifies by hitting the endpoint until throttled and pasting the 429 response.
Example 2: Unfamiliar bug
User says: “Figure out why login intermittently 500s, then fix it.”
- Explores: greps the auth path, reads the session store code, pipes in the real stack trace.
- Writes a short plan pinpointing the suspected race in token refresh.
- Implements the fix, then verifies by reproducing the original failure and showing it now passes —
not by asserting the change “should” fix it.
