Skip to content
Michi v2026.11.16
Save the Tokens

michi-planning

The planning skill prepares a milestone for Michi execution. It bridges the gap between “we know what to build” and “the agent can implement it.” The output is a plan doc that serves as a contract for the implementation session — scope, acceptance criteria, verification scenarios, and numbered steps.

  • Before any implementation session — this is the mandatory predecessor to /michi-session
  • When scoping a new milestone within an existing epic
  • When the spec exists but hasn’t been broken into implementable steps
  • For both code milestones (features, fixes) and non-code milestones (research, design reviews, roadmaps)

The skill runs through a structured process, with human collaboration at each stage.

Assess Complexity and Uncertainty. Before exploring, the agent rates the milestone Low, Mixed or High on complexity (greenfield or legacy, repo size, tight constraints, rigid dependencies) and uncertainty (novel domain, unclear requirements, test coverage, prior agent exposure). It records the reading and its reasoning at the top of the plan doc. If the reading is High or Mixed, it flags this and asks you to confirm pacing before going further.

Explore the codebase. Before writing anything, the agent reads the areas of code the milestone touches. It maps existing patterns (routes, tests, repositories, naming conventions) and identifies files that will serve as templates for new code. For brownfield projects with context-capture artifacts (HAR files, screenshots), it reads those alongside the code.

Surface assumptions and ask questions. The agent explicitly identifies assumptions about the system, the user, and integration boundaries — then challenges each one. It asks clarifying questions about contracts, constraints, and design decisions that affect the public API or data model. Implementation details the agent can decide itself are not surfaced as questions. Questions come one at a time at the end of a turn, each with the few sentences of context you need to answer it; only questions that are genuinely one decision are batched.

Co-design verification scenarios. Spec and verification are designed together — defining “how will we verify this?” shapes the spec itself. The agent works with you to write 3-5 scenarios as stories about users getting benefits, decomposed into Given-When-Then steps. Each scenario is categorized by verification level: A (agent executes autonomously), B (agent executes, judgment needed), or C (human evaluates).

State behavior in the spec. When the agent writes or revises the epic’s spec.md, it asks every time whether the epic changes anything users, callers or other projects already rely on. Behavior goes in its own section, apart from design decisions, as rules a tester who has never seen the code could check. Each change to existing behavior is labeled with what it was and what it becomes, and copied into the scope of the plan that makes it, so the session sees it; if there is none, one line says so.

Write the plan doc. The agent produces a plan doc with context, scope, acceptance criteria, scenarios, numbered implementation steps with file paths, and empty sections for decisions, notes, and discussion items that get filled during implementation. If the epic has a north-stars.md (your fixed points for the epic), the Context section quotes it with a line on how this milestone serves them; a tension with one goes to ## Discussion. For a new epic without one, the agent proposes up to five candidates and you accept the wording; it never writes the file unasked.

Self-review. Before presenting the plan, the agent checks for placeholders, internal consistency (do scenarios match acceptance criteria? do steps produce what scenarios verify?), and assumption coverage.

  • Plan doc at docs/epics/<epic>/plans/<milestone>.md — the implementation contract
  • Test plan at verification/test-plan.md — auth strategy, tooling decisions, test organization (created or updated)
  • Scenario catalog at verification/scenarios.md — seeded with the first milestone’s scenarios, grows over time
  • “Not ready to plan yet” is a valid outcome. If the spec has unvalidated dependencies, the acceptance criteria wait on a decision you haven’t made, or the behavior is too undefined for Given-When-Then, the agent names what’s missing and what would unblock it (an exploration session, a spike, a decision from you) and stops without writing a plan.
  • First-epic planning is different. A first epic is implicitly High Complexity/Uncertainty, so Paired mode is the default. The starting spec is treated as a hypothesis — the agent validates referenced dependencies, surfaces assumptions about external formats, and corrects factual errors without waiting for permission.
  • Non-code milestones use exit criteria instead of verification scenarios. The same planning process applies, but the verification section defines how you’ll know each deliverable is done.
  • Cross-package impact gets explicit attention. The agent checks for new types, enum values, downstream schemas, and hardcoded assumptions — this is where Round 1 bugs came from.
  • The plan is a contract. Implementation executes against it. The natural next step is /michi-session.

For the full agent instructions, see the SKILL.md source.