Metis Plan Task

---
name: metis-plan-task
description: Produce an implementation plan for a free-text task description. Plan stays in chat.
---

# $metis-plan-task

Produce one implementation plan for a free-text task description. The plan stays in chat; nothing is written to disk.

## Arguments

- **Trailing task** — optional. What to plan: a `BUILD.md` item title, a more specific description of the next slice of an item already in progress, or free text. An item can take more than one plan → implement → review task to finish, so the argument can be narrower than the whole item; `CURRENT.md` carries what's left of an in-progress item.
- **No argument** — present the `To build` items as a pick-one selector, with the active task from `CURRENT.md` (the item in flight, or next up) as the recommended first option and an escape hatch for free text. Wait for the pick before planning. If there is no backlog and nothing active, ask plainly what to plan.

## Context expected from session-start

`.metis/CURRENT.md`, `.metis/SYNTHESIS.md`, `.metis/INDEX.md`, and `.metis/BUILD.md` (when they exist) are expected to be in context already (loaded by `$metis-session-start`). `SYNTHESIS.md` is what's being built; `BUILD.md` holds the item's backlog entry; `CURRENT.md`'s *Active task* and *Current state* say which item is live and, for an item already in progress, what's done and what's next; `INDEX.md` is the concept → source-doc map for finding the passages an item points at.

If any is missing — the session began without a session-start — read them lazily as the plan turns on them. Subsequent turns are cache hits.

## Load (task-specific)

- The source-doc passages or code seams the item points at. Use the item's doc links (and `.metis/INDEX.md` for concepts it names) to resolve source-doc paths, then read the docs there — that is where the architectural reasoning the plan must respect lives.
- `.metis/CURRENT.md`'s *Current state*, when planning the next task of an item already in progress — so the plan covers what remains, not work already done.
- `metis-code-explorer` subagent dispatches when the surface is unfamiliar enough that planning would be guessing.
- `metis-domain-researcher` subagent when a plan step would commit to a technical choice the corpus does not cover.

## Do not load

- `.metis/CONTRADICTIONS.md`, `.metis/QUESTIONS.md`, `.metis/RESOLVED.md` — these belong to the reconcile/walk flow, not to planning.
- Other session state beyond `SYNTHESIS.md`, `CURRENT.md`, the item's `BUILD.md` entry, and what the item points at.

## Read first

This skill's `references/planning-a-task.md` — read before drafting.

## Write scope

None. The plan is presented in chat as structured markdown. If the session ends mid-plan or before implementation, `$metis-session-end` captures the relevant plan content in `.metis/CURRENT.md` so the next session can resume.

## Invocation prompt

The free-text after the command is the planning prompt, and it is optional. When absent, present the selector described in *Arguments* rather than guessing.

## Return

The plan, in chat, with the shape from this skill's `references/planning-a-task.md`. When this is the first plan for an item that needs more than one task, the plan also names the item's remaining tasks, so `$metis-session-end` can record that finishing this task does not finish the item.

After the plan: one line on the next step (`$metis-implement-task` to execute), and a tip: *"For Claude Code's native plan-mode review UI, run this in plan mode (Shift+Tab) before invoking."*

If the task appears already substantially done (per the "already done" check in this skill's `references/planning-a-task.md`), return the evidence finding instead of a plan.