/plan — brainstorm → task docs

/plan <description of what to build/change>   split into tasks and write the docs
/plan --problem <report of the finding>        record a problem WITHOUT stopping whoever found it
/plan --revise <slug>                          refine an existing task

Read ../orchestrate/CORE.md §1 — the adapter (.claude/orchestrator.md, found walking up from cwd) provides vault.cards, backlog.*, the size scale and layers. No adapter → CORE §9 bootstrap; do not invent a docs path.

Companions: /dotask runs one task created here; /orchestrate sequences several. This skill only PLANS and WRITES.

Step 1 — Real context before any task

• Understand the request against the code as it IS: a code-graph query (if you have one) + reading the entry point. A task planned only from the request's text is born wrong — text describes intent, not what exists.
• Reality filter (CORE §1.4): was the request (or part of it) already done? git log <base> --grep, the named artifact in the code. Already there → report it with the evidence (sha, file:line) and do NOT create the task.
• Ambiguity that reading the code does not resolve → ask before splitting (one question at a time). Preference and validating the obvious do not count (CORE §10).

Step 2 — Split

• Smallest sensible deliverables; each task = one PR that stands on its own.
• Per task: short title, repo/layer (adapter vocabulary), size on the adapter's scale (default XS|S|M|L|XL), priority (urgent|high|normal|low — required), depends_on (slugs/ids that must close first).
• Two tasks crossing the same files → note the collision in both tasks' Technical notes (/orchestrate uses it to keep them out of the same batch).

Step 3 — Confirm BEFORE writing

Show the table (title · size · priority · repo · depends_on · one-line scope) and STOP — the human confirms, edits or cuts. It is this skill's only human gate. Exception: --problem mode does not pause — a record is not a decision; write and report.

Step 4 — Write the docs

One file per task: <vault.cards>/<kebab-slug>.md. The slug is the local id — it is what /dotask receives. Task template (also in examples/task.md):

---
card_id:
title: "<slug> — <short title>"
status: backlog
priority: <urgent|high|normal|low>
size: <XS|S|M|L|XL>
difficulty: <low|medium|high>
model_exec: <alias for --model at dispatch — guide below>
model_review: <alias for the independent pre-PR reviewer — guide below>
repos: <repo(s), comma separated>
branch:
depends_on:
epic:
updated: <YYYY-MM-DD>
type: task
origin: plan
---

# <short title>

## What
<the deliverable in 1–3 sentences — what changes in the system when this closes>

## Why
<motivation tied to a fact: the task/PR/incident it came from, the risk it covers>

## Acceptance criteria
- [ ] <verifiable, with HOW to verify (command, screen, API call …)>
- [ ] <…>

## Technical notes
<file:line, what already exists, constraints, reference PR/commit, collisions>

## Current state
<one self-contained line — a tracker sync can use it as the card description>

## Links
- <repo / integration / related tasks / permanent notes>

## Session log
### <YYYY-MM-DD> — created by /plan
- **Changed:** task created from <request/context>.

Template rules:

• An acceptance criterion is verifiable: each one says HOW to verify it. "Works correctly" is not a criterion; gh api repos/<owner>/<repo>/rules/branches/main showing the check is.
• Technical notes carry the context you already paid to gather — file:line, what exists, where it came from. Whoever executes should not rediscover any of it.
• Dates: date +%F. Never from memory.
• epic: is optional — fill it when the split came from an epic (status_push runs once per epic).
• Slug collision: a file with that name already exists → do NOT overwrite. Same task → it is a --revise case (append, do not recreate); different task → suffix the slug; in doubt, resolve it at the Step 3 gate.

Difficulty and models — who executes and who reviews

size measures duration; difficulty measures the risk of getting it wrong. A giant rename is L/low; a concurrency fix is S/high. The pair picks the models (aliases of claude --model; the doc WINS over the adapter's model_by_size at dispatch):

Deviating from the table → justify it in the Technical notes. In doubt between two levels, pick the higher one: a stronger review is cheap next to a wrong PR.

Step 5 — Report

Slugs created + how to continue: /dotask <slug> (run one) · /orchestrate <slugs> (sequence several) · tracker sync (if you use one — a separate, human call).

--revise mode — refine an existing task

Reopen <vault.cards>/<slug>.md and apply Steps 1–3 to it (real context again — the code may have moved since it was created). Rules:

• Keep card_id — the tracker card stays the same.
• May change size/difficulty/model_*/depends_on/criteria — and goes through the Step 3 human gate like any plan.
• Log it in ## Session log (### <date> — revised by /plan --revise, saying what changed).
• Task at 🔄/⏳ in some manifest → do not revise under a running agent: report and stop.

--problem mode — record without stopping anyone

For a bug/unexpected behaviour found in the middle of other work (by you, by the human, or by a /dotask kitchen session — the "detour rule" there points here). Rules:

1. Do not fix. Recording is not executing; fixing here is scope leak.
2. Do not stop the caller. Whoever was executing carries on with the original task.
3. Real evidence: file:line of the culprits, grep output, origin PR/epic — no "it seems". Without enough evidence, write what remains to be verified.
4. Dedup: before creating, search <vault.cards> for a similar symptom. Already there → add the new evidence to the existing doc instead of duplicating.

Problem template (same front matter as a task, with origin: plan--problem and found_during):

---
card_id:
title: "<slug> — <symptom in half a line>"
status: backlog
priority: <estimated from the evidence — production broken or data being corrupted → urgent/high; say you estimated>
size: <estimated — say you estimated>
difficulty: <estimated — a bug of unknown cause is never "low">
model_exec: <per the difficulty table>
model_review: <per the difficulty table>
repos: <repo where the bug lives>
branch:
depends_on:
updated: <YYYY-MM-DD>
type: task
origin: plan--problem
found_during: "<slug/id of the task running when the problem showed up>"
---

# <symptom in half a line>

## Symptom
<the wrong behaviour, from the point of view of whoever uses the system>

## Origin
<repo · origin epic/PR · file:line of the culprits — with what grep/reading proved, e.g.
"loadDraft defined in draft-storage.ts:22 but NOT called anywhere (grep: definition +
test only)">

## How to reproduce
1. <concrete step>
2. <concrete step>
3. <concrete step>

## Expected vs. actual
**Expected:** <the promised behaviour, with the reference (design/spec/card) that promises
it> / **Actual:** <what happens>. Side effect: <secondary effect, if any>.

## Current state
Problem recorded via /plan --problem during <found_during> — evidence above; no fix applied.

## Session log
### <YYYY-MM-DD> — recorded by /plan --problem
- **Changed:** record created; no fix applied (detour rule).

This skill does NOT

• Execute, open a PR or create a branch — that is /dotask / /execute.
• Push to a tracker — that is a separate call.
• Create a task for something that already exists (reality filter first, always).
• Fix the problem it is recording (--problem mode).
• Write outside <vault.cards> or invent fields outside the template.