thorough-plan

Thorough Plan

An adaptive exploration loop that prevents premature planning. Builds context through codebase exploration, targeted research, and user questions — then hands off to the normal planning flow.

This is not a planning framework. It's a context amplifier.

Agents fail at planning in predictable ways: - They plan from incomplete briefs and make wrong assumptions - They ask questions they could answer by reading the code - Or they interrogate exhaustively when the task is straightforward

This skill injects judgment: explore what you can, ask what you must, stop when you know enough.

Triage

Read the brief. Evaluate along these dimensions:

• Ambiguity — multiple valid interpretations? unclear boundaries?
• Scope — how many files/systems? cross-cutting concerns?
• Risk — breaking changes? security? data migration?
• Novelty — unfamiliar library? new pattern for this codebase?

Low on all → skip exploration. State your understanding of the task and proceed directly to planning. Don't explore for the sake of exploring.

High on any → enter the exploration loop. Focus exploration on the dimensions that are actually uncertain.

Brief: "Add a /sweep command that cleans up stale git branches"

• Ambiguity: low — intent is clear
• Scope: medium — needs new command + script, touches plugin structure
• Risk: low — read-only git operations, no data loss
• Novelty: low — similar commands exist in git-tools/

→ One focused Explore agent on git-tools/ patterns, then proceed to planning. No user questions needed.

Brief: "Redesign how plugins handle configuration"

• Ambiguity: high — "redesign" could mean anything from a new config format to a complete architecture change
• Scope: high — touches every plugin
• Risk: high — breaking change for existing plugins
• Novelty: medium — depends on what approach is chosen

→ Explore current config patterns across plugins, then ask the user what "redesign" means to them before exploring further.

Exploration loop

This is a loop, not a pipeline. Each iteration:

1. Explore — dispatch against specific unknowns, not the whole codebase.

Unknown type	Tool
Codebase structure, existing patterns	Explore subagent
Library API, version-specific behavior	research-agent → Context7
Code examples, implementation patterns	research-agent → exa (get_code_context)
Platform constraints, known issues	research-agent → web search

Default to a single agent per iteration. Multi-agent dispatch is the exception — use it only when unknowns are truly independent and the parallel cost is justified.

2. Assess — what did you learn? what gaps remain?

Share a brief summary with the user — dense, not verbose. A few lines, not paragraphs. Then evaluate the remaining gaps.

3. Decide — what to do next.

• Gaps resolvable by further exploration → explore again
• Gaps that need user input → ask questions
• User answers that open new branches → explore again
• Remaining unknowns are weak or acceptable → exit loop

Questioning

The format adapts to the dependency structure of the unknowns:

• Independent unknowns → group them. 3 unrelated questions in one AskUserQuestion is efficient.
• Dependent unknowns → sequence them. Answer to Q1 determines whether Q2 matters.
• Single blocker → ask just that one.
• No unknowns left → don't ask anything.

The test for every question: would the answer change the plan? If not, don't ask it.

Bad: "What testing framework do you prefer?" → Answerable by reading the codebase. Explore first.

Bad: "Should I use a modular architecture?" → Too generic. Doesn't change a concrete decision.

Good: "The brief says 'support SSO' — do you mean SAML, OIDC, or both? This determines whether we need one integration or two." → Blocks a structural decision. Can't be resolved by exploration.

Good (grouped): "Two independent questions: (1) Should this be backward-compatible with existing configs, or can we break the format? (2) Do you want this behind a feature flag?" → Independent unknowns, efficient to ask together.

Stop criteria

Exit the loop when you can credibly answer:

• What needs to change and why
• What existing code/patterns to reuse
• What constraints apply
• What the user actually wants vs what they literally said

Not every unknown needs resolution. Distinguish:

• Blocking unknowns — wrong assumption here means wrong plan. Must resolve.
• Acceptable unknowns — state as explicit assumption, revisit during implementation.

Synthesis

Before proceeding to planning, state your understanding conversationally:

• Key findings from exploration
• Constraints and patterns discovered
• Decisions made (with user or by judgment)
• Remaining assumptions, explicitly listed

No file artifact. This lives in the conversation.

Then proceed to the normal planning flow.

Escape hatch

The user can type ::plan at any point to force immediate transition to planning. When this happens: state your current understanding (even if incomplete), list open assumptions, and proceed.

Principles

Principle	Rationale
Explore only dimensions flagged by triage	Unfocused exploration wastes context and delays planning
Explore before asking the user	The codebase often holds the answer. Reserve user questions for what exploration can't resolve
Every question must have decisional value	A question that wouldn't change the plan is noise
Summaries stay dense: a few lines per round	Verbose reports consume context without adding clarity
Stop on sufficiency, not on a budget	The loop exits when context is adequate, whether that takes 1 iteration or 4
Effort proportional to actual ambiguity	A clear brief with low risk gets minimal exploration. A vague brief with high scope gets thorough investigation
No intermediate artifacts — context builds in conversation	Final planning follows the normal workflow
Default to one agent per exploration step	Multi-dispatch is justified only when unknowns are truly independent