Moe Planning

---
# moe-generated: sha=7ff6711d0f28
name: moe-planning
description: Use when an architect is turning a Moe task into an implementation plan via moe.submit_plan. Provides the canonical 8-phase template (plan, explore, tests, minimum impl, verify, document, adversarial review, QA loop), rules for when to skip phases on trivial tasks, and where the verification gate belongs — once at the end of a task, and at full scope only on the epic's final task.
when_to_use: After moe.get_context returns a PLANNING task, before drafting implementationPlan.steps for moe.submit_plan.
allowed-tools: Read, Grep, Glob, WebFetch
---

# Moe Planning — 8-Phase Plan Template

Your job: turn the task in front of you into an implementation plan that a worker can execute without guessing. Use the 8 phases below as the **default skeleton** for the steps you submit via `moe.submit_plan`. Skip phases that genuinely don't apply — but skip *consciously*, not by accident.

## Size triage — before drafting steps

Count before you draft. If an honest plan needs **more than 8 steps or more than 5 distinct `affectedFiles`**, the *task* is too big — no plan fixes that. Do not pad several actions into one step to duck the cap: the step still executes at its real size, and the daemon counts distinct files regardless. `moe.submit_plan` returns `warnings` past 8 steps / 5 distinct files and hard-rejects past 12 steps / 10 distinct files with `CONSTRAINT_VIOLATION` (thresholds: `project.json` `settings.taskSizing`). Right-sized is ≤60 min human-equivalent, 1–3 files, one deliverable.

Oversized means go back to breakdown, not to a denser plan: create smaller sibling tasks via `moe-epic-breakdown` (SPIDR split) and narrow this task to the first slice — or `moe.report_blocked` with the proposed split if the task isn't yours to split.

Then shrink what survives. Load `ponytail` before drafting: a step that reuses an existing helper, a stdlib call, or a native platform feature is one step where a hand-rolled equivalent is four — the ladder is the cheapest route under the size cap. It shortens the solution, never the reading, and it never trims a DoD item, a rail, or a verification step: those are requested work.

## Where the gate goes — read this before drafting steps

Verification is a real cost. Paying it on every step of every task is how a 12-task epic turns into work that is 80% ceremony. Concentrate it instead:

- **Inside a task: the gate is at the end, not on every step.** A step is *implement the thing + write the tests for the thing it changed*. There is exactly **one** adversarial self-review step, and it is the last one. The regression run happens **once**, before `moe.complete_task`. Never emit a "verify" / "review" / "run the suite" step after each implementation step.
- **Inside an epic: the gate is on the last task, not on every task.** Mid-epic tasks build their slice, prove that slice with focused tests, and hand off. The epic's **final** task is where the full-system check lives: full suite, cross-package integration, docs sweep, adversarial pass over the whole epic diff.

So when you decompose a big epic, **end it with an explicit integration-and-hardening task** (`moe.create_task` with the highest `order`). That task owns the epic's end-to-end verification, its documentation, and its "would I be embarrassed if this shipped" pass. Everything before it stays lean and moves. Decomposing an epic is its own pass with its own skill — `moe-epic-breakdown`; this skill starts once the tasks exist and you're planning one of them.

"Lean" does **not** mean sloppy. Mid-epic tasks still write real tests for their own behavior, still handle errors, still get reviewed by QA. Lean means their tests are scoped to what *they* changed and their verification command is the targeted suite, not the whole system.

### Verification depth by epic position

| Task position | Tests to plan | Verification step to plan |
|---|---|---|
| Mid-epic (any task that isn't the last) | Focused unit tests for the behavior this task changes | The one package's suite, or the single test file — name it, keep it narrow |
| Epic-final, or a standalone task with no epic siblings | The above, plus integration / end-to-end covering the epic's whole flow | Full regression across every affected package + adversarial review of the epic diff |
| Any position, if the task touches shared types, schema, wire protocol, or migrations | Whatever the change needs | Full regression regardless of position — these break things outside the task's blast radius |

If you can't tell where the task sits, `moe.list_tasks {epicId}` and compare `order` against the siblings. No epic siblings → treat it as epic-final.

## The 8 phases

### Phase 1 — Plan before you touch anything
Read `task.description`, `task.definitionOfDone`, the linked epic rails, and any `KNOWN_ISSUES.md`. Build a structured todo list before referencing a single line of code. Size the work: how many files? Cross-cutting? Architectural impact? Use the answer to decide which later phases apply.

### Phase 2 — Explore before you assume
Don't reference a function, model, method, relationship, or constant you haven't grepped for. Hallucinated `user.clientProfile.accounts`-style chains are the #1 source of plan-time errors. If the skill `explore-before-assume` is available, invoke it now.

### Phase 3 — Plan tests first
For every behavior change, name the test that proves it. Use mutation-resistant assertions: `assertEquals('completed', $r->status)` not `assert($r)`. Tests that pass when code does nothing are worse than no tests. If the skill `test-driven-development` is available, reference it for the worker.

Scope the tests to *this* task's behavior. Don't plan end-to-end or full-system tests on a mid-epic task — those belong to the epic's final task, where the whole flow actually exists to be tested.

If the breakdown created a sibling **test-authoring task** for this behavior, plan against those held-out tests: name the test files in the steps, make the final verification step "the tests from task-<id> pass unchanged", and never plan a step that edits them — QA rejects a diff that weakens held-out tests.

### Phase 4 — Plan the minimum implementation
Each step does one thing. No clever abstractions. No "while we're here." Scope creep is a bug that looks like progress.

### Phase 5 — Plan the regression check, sized to position
Name the suite the worker runs **once**, before `moe.complete_task` — and size it per the table above. Mid-epic: the narrow suite covering this task's slice. Epic-final, standalone, or shared-surface change: the broader suite, named explicitly (which packages, which command). One verification step per task, never one per implementation step.

Name **one exact command**. This command IS the worker's completion evidence: `moe.complete_task` requires `verification: { command, exitCode, outputTail }` and rejects without it, so the worker runs the command you name here fresh and submits its result — and QA re-runs the same command to audit. `npx vitest run src/server/McpAdapter.test.ts`, not "run the tests".

### Phase 6 — Plan the documentation
Inline comments only where the *why* is non-obvious. Changelog entry if user-visible. Update `docs/` if any contract changes. On a big epic, hold the docs sweep for the final task rather than re-editing the same doc from every task in the epic — unless this task alone changes a contract someone else is about to build against.

### Phase 7 — Plan the adversarial review — one, at the end
Every plan ends with **exactly one** explicit "self-review" step, and it is the final step of the task. Not one per implementation step. On a mid-epic task it is scoped to this task's own diff; on the epic's final task it sweeps the whole epic diff. The checklist:
- What if this runs twice concurrently?
- What if input is null / empty / negative / huge?
- What assumptions am I making that could be wrong?
- Would I be embarrassed if this broke in prod?

### Phase 8 — Plan the QA loop
The worker's job ends at `moe.complete_task`. The QA agent reviews and may call `moe.qa_reject` with `rejectionDetails`. Your plan must hold up under that scrutiny — surface the edge cases and failure modes *in the plan itself* so they don't show up as rejection notes.

## How phases map to plan steps

One step per phase is a fine starting point for non-trivial work. For larger tasks, Phase 4 (minimum implementation) usually expands into multiple steps — one per logical concern. **Only Phase 4 expands.** Phases 5 and 7 are one step each, at the end, no matter how many implementation steps precede them. Always:

- Set `affectedFiles` tight per step.
- Map every Definition-of-Done item to at least one step.
- State non-obvious design choices in the step `description` so the worker doesn't re-derive them.

## When to skip phases

Skip aggressively for genuinely trivial work. A typo fix doesn't need 8 steps.

| Task type | Default skeleton |
|-----------|------------------|
| Doc-only / typo / config tweak | Phases 1, 4, 6 |
| Bug fix, narrow scope, has repro | Phases 1, 3, 4, 5, 7 |
| Mid-epic slice of a larger epic | Phases 1, 2, 3, 4, plus a **narrow** 5 — the epic's final task carries full-scope 5, 6, and 7 |
| New feature, single subsystem (no epic siblings) | Phases 1, 2, 3, 4, 5, 6, 7 |
| Epic-final integration / hardening task | All 8, with 5 and 7 at full-system scope across the epic diff |
| Cross-cutting refactor / migration | All 8 phases, multiple steps in 4 |
| Reopened (`reopenCount > 0`) | All 8, plus a Phase 0 "address rejectionDetails" step |

## Production concerns to bake in (across all phases)

- Errors: every IO / external call has a real handling path
- Resource cleanup: file handles, sockets, listeners closed on every exit path
- Cross-platform: paths, scripts, line endings (this repo ships on Win/Mac/Linux)
- Security: no command injection, no path traversal, no secrets in logs
- Performance: no obvious O(n²) on growing lists, no synchronous IO in hot loops
- Backwards-compat / migration / feature-flag if risky

## When to bail

If the task conflicts with an existing rail, requires missing prerequisites, or is ambiguous in a way only a human can resolve — call `moe.report_blocked` instead of submitting a bad plan.