/omk-planning

name: omk-planning
description: "Full plan lifecycle: deep understanding → write plan with TDD checklist → parallel review → Ralph Loop execution. Trigger when user says 'plan', 'design', 'implement', 'build', 'architect', '@plan', '@execute', or describes a multi-step task that needs structured breakdown. Also trigger for feature requests, system redesigns, or migration projects."

Trigger Examples

• "@plan 重构 hook 系统"
• "I want to add OAuth support, help me plan it"
• "设计一个新的 knowledge 同步方案"
• "@execute 继续执行计划"
• "break this feature into tasks"

Planning — Write, Review, Execute

Overview

One skill for the full plan lifecycle: write → review → execute.

Phase 0: Deep Understanding

Before writing any plan, build deep understanding of the goal. Skip this phase only if the user provides a fully specified design doc.

Step 1: Form Initial Understanding

Start with `generate_codebase_overview` to get the project's high-level structure, then read relevant code, docs, and recent commits to understand the context. Do NOT ask questions yet — first build your own mental model of:

• What the user wants to achieve
• What exists today (current state)
• What would need to change (gap analysis)

Step 2: Ask Clarifying Questions

Based on your understanding, ask questions **one at a time**. Each question must:

• Eliminate a whole branch of ambiguity (not trivial details)
• Build on previous answers (incremental deepening)
• Offer multiple-choice options with your recommendation when possible

**Dynamic termination:** Stop asking when remaining uncertainty won't materially affect the plan. Don't ask for the sake of asking.

**Soft cap:** Maximum 5 questions. If you still have uncertainty after 5, state your assumptions and proceed.

Step 3: Research (optional)

After questions are answered, judge whether research is needed:

• **Codebase research:** When the task touches existing code you haven't fully explored (e.g., modifying a hook system — read existing hooks first)
• **Web research:** When the task involves external tools, APIs, or best practices you're unsure about (e.g., integrating a new library, adopting an unfamiliar pattern)
• **Both:** When the task combines internal changes with external dependencies (e.g., adding OAuth to an existing auth module)
• **Skip:** When you have sufficient understanding (e.g., renaming a variable, fixing a typo, simple refactors with clear scope)

**Research dimension principle:** When research IS needed, cover both theoretical foundations (papers, docs, design rationale) AND engineering practice (real implementations, battle-tested patterns, known pitfalls). One without the other leads to either ivory-tower designs or cargo-culted solutions.

This is your judgment call — not every plan needs research.

Step 4: Supplementary Questions (if any)

After research, absorb what you learned. Only ask the user about findings you **cannot resolve from research alone** — things requiring user decisions or preferences.

If no supplementary questions needed, proceed directly to Phase 1.

Step 5: Design presentation (optional)

When the task involves creative/architectural work (new features, new components, significant behavior changes), present the design before writing the plan:

• Break the design into sections of 200-300 words
• Ask after each section whether it looks right so far
• Cover: architecture, components, data flow, error handling, testing
• Write the validated design to `docs/designs/YYYY-MM-DD-<topic>-design.md`

Skip this step for simple refactors, bug fixes, or tasks with a fully specified design doc.

Step 6: Readiness Check

Before proceeding to Phase 1, verify the task is well-defined across 4 dimensions:

| Dimension | ✅ Criterion | Greenfield | Brownfield | |-----------|-------------|------------|------------| | **Goal** | 能用一句话无歧义地说清楚要做什么 | Required | Required | | **Constraints** | 边界、非目标、限制条件已明确 | Required | Required | | **Success Criteria** | 至少有 2 个可测试的验收标准 | Required | Required | | **Context** | 理解被修改的现有代码/系统 | Skip | Required |

Rules:

• All applicable dimensions must be ✅ to proceed to Phase 1
• If any dimension is ❌, ask ONE question targeting the weakest dimension
• This step adds at most 3 questions (on top of Step 2's questions)
• User says "skip" → state assumptions and continue

**Challenge Modes** (activate on 2nd+ question in this step):

• **Contrarian** (2nd question): "如果 [核心假设] 是错的呢？"
• **Simplifier** (3rd question): "最简版本是什么样的？"

Transition to Phase 1

Goal-Backward Derivation

After the Readiness Check, reverse-engineer from Success Criteria before writing the plan:

For each Success Criterion: 1. **What must be TRUE** for this criterion to pass? 2. Which of these truths **already exist** in the codebase? 3. Which must be **newly created**? → These become Tasks 4. What are the **dependencies** between new truths? → These determine Task order

This ensures the plan covers everything needed for the goal, not just what seems obvious forward-thinking.

Socratic Self-Check

Then validate each major design decision: 1. **Essence** — What is the core problem this decision solves? 2. **Framework** — Does the current codebase already solve this? What known patterns apply? 3. **Application** — Is this feasible on all target platforms? Does benefit > maintenance cost?

Drop any decision that fails step 2 (already solved) or step 3 (infeasible/not worth it).

Then proceed to Phase 1 with the accumulated understanding.

Error Handling

• **No relevant code/docs found:** Inform the user, ask them to point you to the right area, then continue.
• **User wants to skip Phase 0:** Allowed. User can say "skip questions" or "just write the plan" at any time. State your assumptions and proceed to Phase 1.
• **Contradictory answers:** Surface the contradiction to the user, ask them to clarify which direction to take.
• **5-question cap reached with critical ambiguity:** State remaining assumpt