plan

Structured Planning

Verification-driven task decomposition with Sibyl-native tracking. Mined from 200+ real planning sessions: the plans that actually survived contact with code.

Core insight: Plans fail when steps can't be verified. Decompose until every step has a concrete check. Track in Sibyl so plans survive context windows.

The Process

digraph planning {
    rankdir=TB;
    node [shape=box];

    "1. SCOPE" [style=filled, fillcolor="#e8e8ff"];
    "2. EXPLORE" [style=filled, fillcolor="#ffe8e8"];
    "3. DECOMPOSE" [style=filled, fillcolor="#e8ffe8"];
    "4. VERIFY & APPROVE" [style=filled, fillcolor="#fff8e0"];
    "5. TRACK" [style=filled, fillcolor="#e8e8ff"];

    "1. SCOPE" -> "2. EXPLORE";
    "2. EXPLORE" -> "3. DECOMPOSE";
    "3. DECOMPOSE" -> "4. VERIFY & APPROVE";
    "4. VERIFY & APPROVE" -> "5. TRACK";
    "4. VERIFY & APPROVE" -> "3. DECOMPOSE" [label="gaps found", style=dashed];
}

---

Phase 1: SCOPE

Bound the work before exploring it.

Actions

1. Search Sibyl for related tasks, decisions, prior plans:

   sibyl search "<feature keywords>"
   sibyl task list -s todo
   

2. Define success criteria: what does "done" look like?

   • Measurable outcomes (tests pass, endpoint returns X, UI renders Y)
   • NOT vague goals ("improve performance" → "p95 latency < 200ms")

3. Identify constraints:

   • Files/modules that CAN'T change
   • Dependencies that must be respected
   • Timeline or budget considerations

4. Classify complexity:

   Scale	Description	Planning Depth
   Quick fix	< 3 files, clear solution	Skip to implementation
   Feature	3-10 files, known patterns	Light plan (this skill)
   Epic	10+ files, new patterns	Full plan + orchestration
   Redesign	Architecture change	Full plan + research first

Gate

If this is a quick fix, stop planning and go build. Planning a 5-minute fix is waste.

---

Phase 2: EXPLORE

Understand the codebase surface area before decomposing.

Actions

1. Map the impact surface: which files/modules will this touch?

   • Spawn an Explore agent if the scope is uncertain
   • Read the actual code, don't guess from file names

2. Identify existing patterns:

   • How does similar functionality work in this codebase?
   • What conventions exist? (naming, file structure, test patterns)

3. Find the dependencies:

   • What must exist before this can work?
   • What will break if we change X?

Output

A mental model of the change surface:

"This touches: [module A] (new endpoint), [module B] (type changes), [module C] (tests). Pattern follows [existing feature X]. Depends on [infrastructure Y] being available."

---

Phase 3: DECOMPOSE

Break work into verifiable steps. Every step must have a check.

The Verification Rule

A step without a verification method is not a step, it's a hope.

For each task, define:

Field	Description
What	Specific implementation action
Files	Exact files to create/modify
Verify	How to confirm it works
Depends on	Which tasks must complete first

Verification Methods

Method	When to Use
typecheck	Type changes, interface additions
test	Logic, edge cases, integrations
lint	Style, formatting, import order
build	Build system changes
visual	UI changes (screenshot or browser check)
curl/httpie	API endpoint changes
manual	Only when no automation exists

Decomposition Heuristics

• 2-5 minute tasks are the sweet spot. If a task takes > 15 minutes, break it further.
• One concern per task. "Add endpoint AND write tests" is two tasks.
• Order by dependency, not difficulty. Foundation first.
• Mark parallelizable tasks. Tasks with no shared files can run simultaneously.

Task Format

## Task [N]: [Imperative title]

**Files:** `src/path/file.ts`, `tests/path/file.test.ts`
**Depends on:** Task [M]
**Parallel:** Yes/No (can run alongside Task [X])

### Implementation

[2-4 bullet points of what to do]

### Verify

- [ ] `pnpm typecheck` passes
- [ ] `pnpm test -- file.test.ts` passes
- [ ] [specific assertion about behavior]

Parallelizability Markers

Mark tasks that can run simultaneously for orchestration:

Wave 1 (foundation):  Task 1, Task 2  [parallel]
Wave 2 (core):        Task 3, Task 4  [parallel, depends on Wave 1]
Wave 3 (integration): Task 5          [sequential, depends on Wave 2]
Wave 4 (polish):      Task 6, Task 7  [parallel, depends on Wave 3]

---

Phase 4: VERIFY & APPROVE

Review the plan before executing it.

Self-Check

Before presenting to the user, verify:

• Every task has a verification method
• Dependencies form a DAG (no cycles)
• No two parallel tasks modify the same files
• Total scope matches the original success criteria
• Nothing is over-engineered (YAGNI check)

Present for Approval

Show the plan as a structured list with waves:

## Plan: [Feature Name]

**Success criteria:** [measurable outcome]
**Estimated tasks:** [N] across [M] waves
**Parallelizable:** [X]% of tasks can run in parallel

### Wave 1: Foundation

- [ ] Task 1: [title] → verify: [method]
- [ ] Task 2: [title] → verify: [method]

### Wave 2: Core Implementation

- [ ] Task 3: [title] → verify: [method] (depends: 1)
- [ ] Task 4: [title] → verify: [method] (depends: 2)

### Wave 3: Integration

- [ ] Task 5: [title] → verify: [method] (depends: 3, 4)

Gap Analysis

After presenting, explicitly check:

• "Is there anything missing from this plan?"
• "Should any of these tasks be combined or split further?"
• "Are the success criteria right?"

---

Phase 5: TRACK

Register the plan in Sibyl for persistence.

Actions

1. Create a Sibyl task for the feature:

   sibyl task create --title "[Feature]" -d "[success criteria]" --complexity epic
   

2. Create sub-tasks for each plan step:

   sibyl task create --title "Task 1: [title]" -e [epic-id] -d "[implementation + verify]"
   

3. Record the plan decision:

   sibyl add "Plan: [feature]" "[N] tasks across [M] waves. Key decisions: [architectural choices]. Dependencies: [critical path]."
   

Adaptive Replanning

Plans change when they meet reality. When a task reveals unexpected complexity:

1. Don't force through. Pause and reassess.
2. Update the plan: add/remove/modify tasks.
3. Update Sibyl: keep the tracking current.
4. Communicate: "Task 3 revealed [X]. Adjusting plan: [changes]."

---

Execution Handoff

Once the plan is approved, hand off to the right tool:

Situation	Handoff
3-5 simple tasks, user present	Execute directly with verification gates
5-15 tasks, mixed parallel	/hyperskills:orchestrate with wave strategy
Large epic, 15+ tasks	Orchestrate with Epic Parallel Build strategy
Needs more research first	/hyperskills:research before executing

Trust Gradient for Execution

Phase	Review Level	When
Full ceremony	Implement + spec review + cross-model-review	First 3-4 tasks
Standard	Implement + spec review	Tasks 5-8, patterns stabilized
Light	Implement + quick verify	Late tasks, established patterns

This is earned confidence, not cutting corners. Run /hyperskills:cross-model-review for any task that touches auth, payments, migrations, or data integrity, regardless of phase.

---

Anti-Patterns

Anti-Pattern	Fix
Planning a five-minute fix	Build directly and verify
Tasks without verification	Add a concrete check or split the task
Parallel tasks touching the same files	Sequence them or repartition ownership
Planning from filenames only	Read the actual code path before decomposing
Treating the first plan as permanent	Replan when reality reveals new constraints

---

What This Skill is NOT

• Not required for simple tasks. If the solution is obvious, just build it.
• Not a design doc generator. Plans are action lists, not architecture documents.
• Not a blocker. If the user says "just start building," start building. You can plan in parallel.
• Not rigid. Plans adapt. The first plan is a hypothesis.