---
name: epic
description: Split a vision or umbrella issue into linked child issues in one batch.
---

# /epic — decompose an umbrella into children

Turn one large item (vision, epic, umbrella issue) into native sub-issues in one pre-validated batch, each linked to its parent: draft the children, validate all, create, confirm the tree.

## Opening branch — no umbrella yet

For a product intent rather than an existing issue: gather the intent, read the repo's live issue templates, draft the umbrella from the matching feature/task template and show the draft for the user's go. Then create one issue with the `epic` label and an explicit Priority field; re-read it from the board to prove body, label and priority landed. Stop there unless child decomposition was also asked for and approved.

## Step 0 — load the umbrella whole

Read the body **and every comment** (later comments supersede):

```bash
mmi-cli oracle board show <owner/repo#N>
```

Slice by deliverable, not phase: each child is independently claimable and lands in its own PR. The parent stays open until the last child merges.

## Step 1 — draft the batch file

Inspect existing children first:

```bash
mmi-cli oracle issue children <owner/repo#N>
```

Write a JSON array, one object per child, to `.jerv/tmp/epic-<parentNumber>-children.json` (unique per epic; a leftover batch from another epic collides with the new rows):

```json
[
  { "type": "task", "title": "C1: extract the shared frame", "body": "…", "priority": "high",
    "surface": "cli", "parent": "owner/repo#42" },
  { "type": "feature", "title": "C2: wire the new command", "body": "…", "parent": "owner/repo#42" }
]
```

- `type` — required: `bug` · `feature` · `task`.
- `title` — required, a short greppable deliverable.
- `parent` — the umbrella (`N`, `#N`, a bare number, `owner/repo#N` or URL); links the child as a native sub-issue on create, so no `link-child` pass. Cross-repo is fine.
- `priority` — `urgent|high|medium|low` (default `medium`); sets the board Priority field.
- `repo` — optional per-row `owner/repo`; defaults to `--repo`, then the current repo.
- `surface` — required when the target repo uses `surface:*` taxonomy, with or without the prefix; top-level `--surface <value>` sets the default.

The batch pre-validates every row before creating any; one bad row fails the set with an aggregate error. A warning that a title closely matches an open child of the same parent must be inspected before creating a duplicate. Get the user's go on the drafted set before writing.

## Step 2 — create the children

```bash
mmi-cli oracle issue create --type task --batch .jerv/tmp/epic-42-children.json --surface cli
```

`--type` is required but each row's own `type` governs. It prints per-row `{number,url}` and fails loud. Add `--idempotency-key <key>` when a retried loop must not duplicate. The lookup is find-before-create, not atomic: one batch writer at a time, never concurrent creates with the same key. Size the command's wall-clock budget for the whole sequential batch; on timeout the outcome is unknown, so confirm the process ended, wait for writes to quiesce, inspect the children, then retry the missing rows with the same key.

Under `mmi-cli vault secrets use GH_TOKEN -- …` the `GH_TOKEN` override can break Hub session discovery and print `board attach skipped — no Hub session token`; that is not proof of placement either way, so verify in Step 3.

## Step 3 — confirm the tree

```bash
mmi-cli oracle issue children <owner/repo#N> --json
```

This JSON is the placement authority: every intended child must be linked and on the board as Todo (`boardStatus` names it). `boardStatus: null` is inconclusive (the walk can miss org-board Status that `board show` still sees); investigate with `board show`. If placement is not proven, correct the misfire. Link a pre-existing child with:

```bash
mmi-cli oracle issue link-child <parent> <child>
```

Each child is now a parallel item: one worktree + PR each. On Windows set `git config core.longpaths true` on the main checkout before the first `git worktree add`. When linked worktrees share a clone, serialize `git branch -m` and other ref renames (or retry serially on `.tmp-renamed-log`). **When the last child merges, close the umbrella** (board `Done` follows).

Never free-type children with raw `gh issue create`: the batch path carries validation, board attach and structured output.

## Retro

Before the final report, ask once: did this skill's own instructions misfire? Process only. If yes, file one lesson (hard cap: one per run); a clean run is silent; if the call fails, note it and continue. Never edit the skill live.

```bash
mmi-cli learning skill-lesson --skill epic --title "<what misfired>" --body "<what; evidence; proposed amendment>"
```