kaimingwan/oh-my-kiro/omk-planning

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:

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 assumptions explicitly, proceed to Phase 1. The plan will note these assumptions for reviewer scrutiny.

Phase 1: Writing the Plan

Save to: docs/plans/YYYY-MM-DD-<feature-name>.md

Plan Header (required)

# [Feature Name] Implementation Plan
 
**Goal:** [One sentence]
**Non-Goals:** [What this plan explicitly does NOT do]
**Architecture:** [2-3 sentences]
**Tech Stack:** [Key technologies]
**Work Dir:** [Relative path to working directory, e.g. `src/` or `.`]
 
## Review
<!-- Reviewer writes here -->

Checklist Format (enforced by hook)

Every plan must have a ## Checklist section. Every checklist item MUST include an executable verify command:

-[ ] description | `verify command`

Examples:

• - [ ] hook 语法正确 | \bash -n hooks/security/my-hook.sh\``
• - [ ] config 包含新 hook | \jq '.hooks' .kiro/agents/pilot.json | grep -q my-hook\``
• - [ ] 外部路径被拦截 | \echo '{"tool_name":"fs_write","tool_input":{"file_path":"/tmp/evil.txt"}}' | bash hooks/security/my-hook.sh 2>&1; test $? -eq 2\``

Rules:

• verify command must be executable (no "手动测试", no "目视检查")
• verify command must return exit 0 on success
• Each Task must have at least 1 checklist item
• Cover: happy path + edge case + integration (where applicable)
• Hook enforces: checking off - [x] requires recent successful execution of the verify command
• Regression test rule: If plan Files fields include scripts/ralph_loop.py or scripts/lib/, the checklist MUST include: - [ ] 回归测试通过 | \python3 -m pytest tests/ralph-loop/ -v\``
• Vertical slice rule: Organize tasks as vertical slices (one feature end-to-end) rather than horizontal layers (all models, then all APIs). Vertical slices have fewer inter-task dependencies, enabling cleaner atomic commits. Exception: tasks that are inherently horizontal (e.g., "add logging to all hooks") need not be forced into vertical slices.

Coarse Checklist Items

Checklist items can be high-level ("coarse") as long as the verify command is meaningful. The executing agent uses the Reasoning Loop (OBSERVE → THINK → PLAN → EXECUTE → REFLECT → CORRECT → VERIFY) to autonomously decompose coarse items into concrete sub-steps.

Fine-grained vs coarse examples:

Rules for coarse items:

• Verify command must still be executable and exit 0 — this is non-negotiable
• Prefer module-level or integration-level test commands as verify (e.g., python3 -m pytest tests/module/ -v)
• The Task body should describe the goal and constraints, not every line of code
• The executing agent will autonomously decompose using the Reasoning Loop

Task Structure (TDD)

Each task follows red-green-refactor:

### Task N: [Component Name]
 
**Files:**
-Create: `exact/path/to/file.py`
-Modify: `exact/path/to/existing.py`
-Test: `tests/exact/path/to/test.py`
 
**Step 1: Write failing test**
[Complete test code]
 
**Step 2: Run test — verify it fails**
Run: `pytest tests/path/test.py::test_name -v`
Expected: FAIL
 
**Step 3: Write minimal implementation**
[Complete implementation code]
 
**Step 4: Run test — verify it passes**
Run: `pytest tests/path/test.py::test_name -v`
Expected: PASS
 
**Step 5: Commit**

Rules: exact file paths, complete code (not "add validation"), exact commands with expected output.

Errors Section (required)

Every plan must have an ## Errors section at the bottom. During execution, log every error encountered:

## Errors
 
| Error | Task | Attempt | Resolution |
|-------|------|---------|------------|

Rules:

• Log immediately when error occurs, don't wait
• Include which Task triggered the error
• Track attempt number — if same error appears at attempt 3, trigger 3-Strike Protocol (see Phase 2)
• This section is append-only during execution — never delete entries
• Cap: keep most recent 20 entries; if exceeded, summarize older entries into a single "Earlier errors: N resolved" row

Findings Section (optional)

Plans may include a ## Findings section for persisting research discoveries made during execution:

## Findings
 
-[discovery with context]

Rules:

• Append-only — never rewrite, only add new entries
• Use when execution-phase research reveals something relevant to later tasks
• Not required for simple plans where no research happens during execution

Session State Section (optional)

Plans may include a ## Session State section for cross-session continuity:

## Session State
 
**Position:** Task N of M
**Last session:** YYYY-MM-DD HH:MM
**Decisions made this session:**
-[decision with rationale]
 
**Notes for next session:**
-[what to pick up, what to watch out for]

Rules:

• Updated at the end of each Ralph Loop round (before agent exits)
• Read at the start of each round (part of Session Resume Protocol)
• Append-only for decisions; position and notes are overwritten each round
• Not required for small plans (≤ 3 items) that complete in a single round

Phase 1.5: Plan Review

After writing the plan, run multi-perspective plan review before execution.

Angle Pool

Two categories: fixed (every round) and random (sampled each round).

Fixed angles (always included):