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.

When to use

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)

What it does

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

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.

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).

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.

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.

What it produces

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

Key things to know

First-epic planning is different. 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.