explore-plan

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.

Before executing: parallelize where independent

This isn't limited to the planning step—apply it to executing any plan (see CLAUDE.md). Once the plan lists concrete files/steps, check whether any of them are independent before running them serially. Independent research (tracing unrelated modules, checking multiple call sites) fans out to parallel Explore agents. Independent implementation (edits to separate files with no shared state or ordering dependency) can run as parallel Agent calls—use isolation: "worktree" if they'd otherwise touch the same files concurrently. Steps stay serial when one depends on another's output (e.g., a schema change before the code that reads it) or when review/verify must see the prior step's result first. Only reach for the Workflow tool when the user has explicitly opted into multi-agent orchestration (see its tool description)—otherwise use direct parallel Agent calls in a single message.

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.”

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: “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.