epic-plan

Files (1)

• SKILL.md

SKILL.md (first lines)

Turn a topic into one **tracker** issue carrying a frozen contract plus
**child** issues each sized for a single `/resolve-issue` session. A wrong
decomposition is the most expensive place to be wrong, so tokens go into the
split and its adversarial review — never into code; handoff ends at the
executors. **No approval gate:** materialize the reviewed decomposition
immediately — it's idempotent, so a user revision afterwards edits issues in
place.

## Re-entry (run first)

- **Tracker number/URL** → already materialized; GitHub is the sole state
  store. Re-sync the tracker checklist against actual child states (children
  close out of band). `needs-revision` label or human comment → re-run the
  review against live state, revise once, re-materialize idempotently — never
  restart or duplicate. Otherwise report shipped / runnable-now / next wave.
  Last child merged → verify the *composed* result against the contract's
  Done criteria (end-to-end, not per-child green), suggest `/simplify-sweep`
  over the epic's range, close the tracker with a one-comment summary.
- **Topic** → new epic. A stable kebab `<slug>` (≤4 words) keys
  `/tmp/epic-plan/<slug>/`, the `epic:<slug>` label, and the idempotency
  markers. Reuse cached research/review from a crashed run only if scope is
  unchanged.
- **Non-tracker issue number** → treat as topic seed (the landing path for
  `/resolve-issue` bouncing an epic); note close-or-supersede in the tracker
  body.

Early exits: **really one issue** → file it, then `/resolve-issue <N>`. **Trivial epic** (2–3
obvious children, no unknowns) → skip research and the panel, decompose,
materialize.

## Contract (freeze before decomposing)

Ask at most one question, only when two readings would produce materially different trackers; otherwise state the assumption and proceed. Refuse to proceed on `TBD` success criteria,
boundaries, or key terms. The contract goes
verbatim into the tracker and binds every child:

- **Definition of done** — concrete: a passing test, a metric, a visible behavior.
- **Out of scope** — the nearest adjacent thing an agent would wrongly pull in.
- **Constraints** — stack, conventions, interfaces that must not change.
- **Repos in play** — multi-repo: each child names its repo; `depends-on`
  orders children within one repo, cross-repo ordering is separate waves.

## Research (skip on trivial epics)

Concurrent read-only recon agents in one message — codebase always; external
landscape only if user-facing or the domain is unclear. Synthesize
works / broken / missing / recommendation to
`/tmp/epic-plan/<slug>/research.md`; the relevant slices feed each child's
Context stanza so executors never re-pay for the recon.

## Decompose into a child DAG

- **Vertically by capability, never by layer** — each child demoable end to
  end.
- **Disjoint file sets are a design goal** — overlap means re-cut the
  boundary first; `depends-on` only when the overlap is real. Overlapping
  siblings left unordered is a decomposition failure.
- **Each Done criterion traces to exactly one child** — untraceable →
  missing child; child proving nothing → invented scope. Genuine unknowns →
  time-boxed spike children gating via `depends-on`.
- Each child: one `/resolve-issue` session; ~8 children max (completion
  velocity collapses above that).

## Adversarial review (skip on trivial epics)

Schema pre-check yourself (every child fully filled), then concurrent
`opus-worker` critics role-locked to find flaws, distinct lenses:
completeness, dependency-ordering, scope/altitude/value, feasibility &
testability, premortem. Synthesize once per
`~/projects/skill-issue/docs/adversarial-review-panel.md` — no loops. Revise once against upheld
blockers; advisories are nudges.

## Materialize (direct `gh`, idempotent) + report

Every create searches for its stable marker first and skips what exists —
re-running never duplicates, so a mid-materialize crash is safe. **Never pair
titles to bodies via shell array indexing** (zsh is 1-indexed; measured
title/body off-by-one) — one explicit create per child. Labels `epic` and
`epic:<slug>` (create if absent; `--limit 999` so pagination doesn't fool the
check). Tracker — dup-check by title under `epic`:

```
<!-- epic-plan:tracker slug=<slug> -->
## Goal
<one paragraph>

## Contract
**Done:** ...
**Out of scope:** ...
**Constraints:** ...

## Children
- [ ] #<n1> <title>  (deps: none)
- [ ] #<n2> <title>  (deps: #<n1>)
```

(Back-fill `## Children` with real numbers via `gh issue edit --body-file`.)

Children — marker is the first body line. List issues under the
`epic:<slug>` label with `gh issue list --label 'epic:<slug>' --json
number,body`, grep each body for the literal marker string, and create only
on exact match failure (fuzzy `--search` produced a false-positive dup that
silently skipped a child — #1651/#1650).

```
<!-- epic-plan:child slug=<slug> ord=<k> -->
## Scope
<one PR's worth>

## Context
<3–5 recon facts this child needs to start cold — the executor must not
re-pay for this.>

## Acceptance criteria
- [ ] <machine-checkable>

## Depends on
#<n>          (or: none)

From fbserg/skill-issue, MIT.

More from fbserg/skill-issue