// Invoke before formalising execution after discovery. Triggers: 'plan this', 'let's plan', multi-step implementation or refactoring, architectural decisions, substantial analysis or validation. Do NOT use plan() to start exploration.
[HINT] Download the complete skill directory including SKILL.md and all related files
| name | planning |
| description | Invoke before formalising execution after discovery. Triggers: 'plan this', 'let's plan', multi-step implementation or refactoring, architectural decisions, substantial analysis or validation. Do NOT use plan() to start exploration. |
A plan is an evidence-backed agreement, not a task list with a header. Before calling plan(), you and the user should share an understanding of what exists, what problem is being solved and why, which approach is being chosen, which trade-offs are accepted, what done looks like, and what is out of scope. Tasks come from that agreement; they are not the plan itself.
Planning turns discovery into approved execution. The plan() tool is for approving the next consequential work phase — implementation, validation, substantial analysis, or another execution workflow — once the context and approach are understood.
Exploration is non-mutative. Read code, inspect docs, search history, run safe read-only checks, and use subagents when useful. Do not use plan() to authorise discovery itself; use it when discovery has produced enough context to propose a bounded execution path.
During exploration, treat early ideas as disposable strawmen: compare them against actual constraints, look for evidence that would make them a poor fit, and revise or discard them before converging. The goal is not to prolong debate; it is to test assumptions and alternatives enough that the final recommendation is justified.
Prototypes, spikes, repo edits, expensive validation runs, and substantial analysis execution require an approved plan and handoff first.
plan()Use plan() when the approach matters and the next work phase needs explicit user approval before execution:
Do not use plan() to begin exploration. If you do not yet understand the current system, constraints, options, success criteria, invalidated alternatives, surviving assumptions, or remaining uncertainty, keep investigating and discussing. For simple, obvious work, use update_goal → create_tasks instead.
Investigate before formalising. Read the relevant code, docs, configuration, schemas, prior decisions, or logs needed to understand the problem. Use the gather skill when user requirements need clarification, and ask only for gaps you cannot resolve from available context.
You are ready to move toward a plan when you can explain what exists, what is changing, why it matters, and what constraints shape the solution from evidence rather than untested assumptions.
Planning is collaborative design work. Surface viable approaches with trade-offs, test them enough to justify convergence, then recommend one and explain why it is the strongest survivor. Challenge scope when the simpler path would satisfy the goal.
Before recommending convergence, test the leading option against disconfirming evidence and compare it with plausible alternatives. It is acceptable to sketch disposable strawmen, then retire them when the evidence or constraints show they do not fit. Preserve the useful learning: which alternatives were invalidated, which assumptions survived, what uncertainty remains, and why the recommended plan survived the comparison.
If the user wants to skip to plan() before the approach is agreed, push back: formalising before shared understanding creates a task list, not a plan.
Good approach discussion answers:
Before calling plan(), align on the boundaries that prevent drift. Decide what the work includes, what it excludes, what success looks like, which assumptions are stable enough to proceed on, and which unresolved questions matter enough to resolve now. Make uncertainty explicit rather than hiding it: if it could change the recommended approach, keep exploring; if it can be managed within the plan, name the risk or boundary. Do not hide unresolved decisions inside tasks; if a task depends on a decision that has not been made, make the decision before formalising.
plan()Call plan() only after discovery and discussion have converged. Convergence requires a final recommendation, not just a list of options: you should be able to state which alternatives were invalidated, which assumptions survived, what uncertainty remains, and why the recommended plan is the best next step. The plan sections should reflect the agreed direction, not introduce new thinking.
plan({
goal: // one sentence — what are we achieving
context: // what exists, constraints, triggers
design: // the agreed approach — patterns, trade-offs, decisions
success: // plan-level success criteria — concrete and verifiable
boundaries: // what's out of scope — prevents drift
tasks: // ordered steps, each with label + description + criteria
worktreeSlug: "handoff-labels" // optional hidden metadata for implementation handoff
})
For implementation plans, include worktreeSlug as hidden metadata: a short semantic kebab-case slug with no session prefix, e.g. handoff-labels. Omit it for analysis-only plans. This is not a user-reviewed plan section; the user sees the worktree selector later and can override the final label there.
The user reviews via an interactive overlay. They may:
If feedback is returned, address it and re-submit. Unchanged approved sections keep their status.
Once every item is approved and submitted, follow the plan result. Implementation plans ask for supervisor vs IC/executor posture; if the approved result includes a scheduled handoff, do not begin implementation in the current turn. End the turn and let Basecamp start the fresh handoff turn so the selected posture prompt is loaded. Analysis-mode plans stay in analysis mode; begin the approved analysis tasks without supervisor/executor handoff.
A good plan is specific enough that another agent could execute without reopening the whole discovery conversation.
The design section is where the thinking lives. Do not just describe what will be built or run; explain the trade-offs and decisions that make this plan coherent.
A plan() call is not:
One sentence. Specific enough that you'd know when it's done.
Migrate user authentication from server-side sessions to JWT with refresh token rotation
Not "improve auth" or "refactor the auth system."
Prose. Supports the goal — why this work matters, what exists today, what triggered it, relevant constraints. The goal says what, context says why now. Don't restate the goal.
Prose. This is the most important section — it's where the thinking lives. Explain the approach and why this approach over alternatives. Don't just describe what you'll build — explain the trade-offs and decisions.
Bullet list. Concrete, verifiable criteria. Each item should be independently checkable.
- p95 latency under 200ms
- Cache hit rate above 80% for product detail endpoints
- No stale data beyond TTL window
- PostgreSQL query volume reduced by at least 60%
Not "it works" or "tests pass."
Bullet list. What's explicitly out of scope. Each item prevents a specific kind of drift.
- No cache invalidation on writes — TTL handles staleness
- No cache warming on deploy
- No distributed cache coordination
- Redis failure = fall through to PostgreSQL
Not "keep it simple" or "no gold-plating."
Ordered list. Smallest meaningful units of work — logical chunks, not individual file edits. Each task needs a label, description (what and why), and criteria (what done looks like for this task). Tasks should follow directly from the agreed approach; if a task requires a decision that has not been made, make that decision before formalising.