name: planning
description: Goal decomposition skill for AI agents. Emphasizes discussion first—clarify and decompose the goal through conversation, then write the plan to markdown only after convergence.

Planning Skill (Goal Decomposition)

This skill helps decompose a high-level goal into executable, verifiable steps. Planning is discussion-first: spend time clarifying, decomposing, and aligning with the user; only after the discussion has converged should you write the plan into a structured document (e.g., Markdown).

When to Use

• The user gives a high-level or vague goal that needs to be broken down.
• The goal involves multiple steps or sub-goals with unclear order or dependencies.
• You need to agree on scope, order, and trade-offs before implementation.
• The user explicitly asks to "plan first" or "discuss how to do this."

When NOT to Use

• The goal is already a single, clear, one-step task.
• The user says "just do it" or "no need to plan."
• The user has already provided a detailed step-by-step plan.

Core Principle

Discuss first, document later. During the planning phase, focus on conversation: ask questions, propose decompositions, and refine based on feedback. Do not rush to produce a full Markdown plan. Only after both sides agree that the goal, steps, and assumptions are clear, write the plan into a structured file.

Phase 1: Discussion

Use this phase to align on the goal and its decomposition. Go through the following questions as needed; not every question applies to every goal. Answer or clarify through dialogue rather than by filling a template.

1. Clarifying the Goal

Ask or clarify:

1. One-sentence goal
2. What is the goal in one sentence?

3. Whose goal is it (user, system, project)?

4. Success

5. What does "done" look like?

6. Is there a concrete, verifiable outcome (e.g., "feature X works in environment Y")?

7. Boundary

8. What is explicitly out of scope for this goal?

9. Is there a "good enough" version vs. a "full" version?

10. Context

11. What is the background or trigger for this goal?
12. What constraints matter (time, tech stack, existing codebase)?

2. Decomposing the Goal

Propose and refine:

1. First decomposition
2. Propose an initial breakdown (e.g., sub-goals A → B → C).

3. State briefly why this order or grouping.

4. Refinement

5. Which steps should be merged, split, or reordered?

6. Is there a "must do first" vs. "can do later or in parallel"?

7. Granularity

8. Is each step a single, actionable unit (one thing to do or verify)?

9. If a step is still vague, split or clarify it.

10. Dependencies

11. Which steps depend on which others?
12. Are there circular dependencies? How to break them?

3. Assumptions and Uncertainty

Make them explicit in discussion:

1. Assumptions
2. What are we assuming (e.g., environment, existing behavior, APIs)?

3. Which assumptions should be validated before or during implementation?

4. Unknowns

   • What is still unclear?
   • What do we need to discover or decide later?

4. Trade-offs and Decisions

Discuss and record:

1. Trade-offs

   • Any trade-offs (e.g., scope vs. time, simple vs. complete)?
   • What was chosen and why?

2. Risks

   • What could go wrong or block progress?
   • Any mitigation in mind (even briefly)?

Discussion output: A shared understanding—e.g., a short mental or informal list of: goal, steps, order, dependencies, assumptions, trade-offs. No formal document is required yet.

Phase 2: Convergence Check

Before writing the plan to Markdown, confirm that the discussion has converged. Use this checklist; if any item is not satisfied, continue the discussion.

Convergence Checklist

• [ ] Goal is agreed

• Both sides agree on the one-sentence goal and success criteria.

• [ ] Steps are concrete

• Each step is a single, actionable or verifiable unit (no vague "figure out X" unless that is the agreed step).

• [ ] Order and dependencies are clear

• Execution order is defined; dependencies have no unresolved conflicts.

• [ ] Assumptions are stated

• Important assumptions are named and acknowledged.

• [ ] Trade-offs are recorded

• Key decisions and trade-offs are clear enough to be written into the plan.

• [ ] Scope boundary is clear

• What is in scope and what is out of scope is agreed.

Only when all applicable items are checked should you proceed to Phase 3 and write the plan to a file.

Phase 3: Write Plan to Document

After convergence, write the agreed plan into a structured document (e.g., PLAN.md or planning-YYYYMMDD.md).

What to Include

1. Goal and success
2. One-sentence goal.

3. Success criteria (how we know we are done).

4. Steps

5. Numbered list of steps (and optionally sub-steps).

6. For each step: short description; dependencies if any; priority if relevant.

7. Assumptions

8. List of assumptions and, if needed, how to validate them.

9. Trade-offs and decisions

10. Key trade-offs and the choices made.

11. Out of scope (optional)

12. What was explicitly excluded.

13. Risks and follow-ups (optional)

14. Main risks and any planned mitigation or follow-up.

Example Structure

# Plan: [Goal title]

**Goal:** [One sentence]
**Success:** [How we know we're done]

## Steps

1. [Step 1]. (Depends: none.)
2. [Step 2]. (Depends: 1.)
3. [Step 3]. (Depends: 1, 2.)

## Assumptions

- [Assumption 1]
- [Assumption 2]

## Trade-offs & Decisions

- [Decision 1]: [Brief reason]

## Out of Scope

- [Item 1]

## Risks / Follow-ups

- [Risk or follow-up 1]

Relationship with Problem Planning

• Planning (this skill): Focuses on what to achieve and in what order—goal decomposition, discussion, then one consolidated plan document.
• Problem Planning: Focuses on how to solve a single, relatively well-defined problem—analysis, design, implementation tasks, validation.

You can use both: first use this Planning skill to decompose a big goal into sub-goals and order them; then use Problem Planning for each sub-goal to design and plan implementation in detail.

Important Notes

1. Do not skip the discussion. The value of this skill is in aligning through conversation; writing the document too early can lock in a plan that is not yet agreed.

2. Use the convergence checklist. Only write the plan when the checklist is satisfied; otherwise, continue discussing.

3. Keep the document aligned with the discussion. The written plan should reflect what was agreed in the discussion, not a new or different plan.

4. Update the plan when things change. If new information or decisions emerge during implementation, update the plan document and, if needed, briefly note what changed and why.