Planning Methodology

A structured approach to planning that ensures clarity before execution. Based on patterns from Claude Code, Cursor, BMAD, and SpecKit.

The Four Phases

Phase 1: Understand

Goal: Gain comprehensive understanding of what the user wants to accomplish.

Activities:

• Listen to the user's initial request
• Identify the core goal (what success looks like)
• Detect red flags: unbounded scope, impossible requirements, vague deliverables
• Note any assumptions you're making
• Consider existing context (see below)

Output: Clear statement of intent with identified gaps

Advance when: You can articulate what the user wants in one sentence AND you've identified what's unclear

Loop back when: User's response reveals the goal was misunderstood

Context Exploration

Before asking questions, consider what you already know:

• Connected services — What integrations are available? (Gmail, Notion, etc.)
• User history — Have they mentioned relevant preferences or constraints?
• Prior conversation — Did earlier messages provide context for this request?
• Domain knowledge — Do you have slices or knowledge relevant to their goal?

Use this context to ask better questions and avoid asking what you already know.

Phase 2: Clarify

Goal: Remove ambiguity through targeted questions.

Activities:

• Ask 1-2 questions that would most unblock the plan
• Push back on impossible or unbounded requests with alternatives
• Confirm scope boundaries (in/out)
• Identify dependencies and prerequisites

Output: Answers to blocking questions, refined scope

Advance when: You have enough information to draft concrete steps

Loop back when: Answers reveal new ambiguities or scope creep

Phase 3: Draft

Goal: Structure the plan with actionable steps.

Activities:

• Break work into discrete, verifiable steps
• Assign each step to a todo item
• Define success criteria for each step
• Identify decision points and dependencies between steps

Output: Structured plan with todos

Advance when: Plan is complete and internally consistent

Loop back when: Drafting reveals gaps in understanding

Phase 4: Finalize

Goal: Prepare the plan for execution.

Activities:

• Add _action frontmatter for "Run Now" button
• Final review for completeness
• Present to user for approval

Output: Executable plan with action button

Complete when: User has the plan and can choose to execute

Phase Transitions

UNDERSTAND
    ↓ Can articulate goal + identified gaps
CLARIFY
    ↓ Have answers to blocking questions
    ↓ (may loop back to UNDERSTAND if goal was wrong)
DRAFT
    ↓ Plan is complete and consistent
    ↓ (may loop back to CLARIFY if gaps found)
ITERATE (optional)
    ↓ User requests changes to draft
    ↓ (loops back to DRAFT until satisfied)
FINALIZE
    ↓ Plan presented with action button
DONE

Iteration is Expected

After drafting, users often want changes. This is normal, not a failure:

• "Can we add another step for X?"
• "Actually, let's remove the Y part"
• "Change the scope to include Z"

Use Iterate Plan to handle revision requests. The loop is: Draft → User reviews → Iterate → User reviews → ... → Finalize.

Key Principles

Think Before Doing

Never jump to drafting before understanding. A well-understood simple plan beats a complex plan built on assumptions.

One Question at a Time

Don't overwhelm with questions. Ask the single most important clarifying question, get the answer, then decide if you need another.

Bounded Scope

Every plan must have clear boundaries. If scope is unbounded ("handle all cases"), push back and propose a bounded alternative.

Actionable Output

Each step should be something the agent can actually do. Vague steps like "improve the system" aren't actionable.

User Checkpoints

The user reviews and approves before execution. The plan is a contract, not a surprise.