pm-prep

What this skill does

# PM Prep

Take a `hitl` issue — one that needs a human at the wheel — sit with the operator long enough to resolve *what* needs the human, write those resolutions into the issue body, and once the issue is specified well enough to run unattended, promote it `hitl → afk`.

## Usage

```
/pm-prep [<issue-id>]
```

- `<issue-id>` *(issue key, optional)* — the `hitl` issue to prepare, e.g. `FUNC-12` (Linear) or `#42` (GitHub). Omit to discover the whole `hitl` backlog and walk it one issue at a time.

No flags. The two writes — the body edit, then the `hitl→afk` retag — are each confirmed interactively; nothing is written without approval.

## Why this skill exists

The plugin already has the two ends of this pipeline:

```
pm-triage              →   ??? (the gap)        →   pm-issue-to-pr
(assigns hitl|afk           (promote hitl→afk        (autonomously works
 at triage time)             once it's ready)         the afk backlog)
```

`pm-triage` labels an issue `hitl` when it needs design judgment, manual verification, or has gaps that block mechanical execution. `pm-issue-to-pr` only picks up `afk` issues, and bounces anything underspecified back to `hitl` with a comment. Nothing in between *moves an issue across that line.* That promotion has always been a manual judgment the operator makes in their head and applies with a label.

The thing that actually makes an issue afk-ready is **content in the body**: filled-in sections, testable acceptance criteria, pinned-down file targets, a chosen design path. And no existing skill writes to the body — `pm-review` scores it, `pm-improve` drafts questions as a comment, `pm-triage` only labels. `pm-prep` fills exactly that gap: it's the interactive, body-editing, promotion-gated workflow that turns "a human needs to think about this" into "an agent can grind through this."

## When NOT to use it

- The issue is already `afk` — nothing to promote. (Offer `pm-review` if they want a structural check, or just hand it to `pm-issue-to-pr`.)
- The issue has **no** execution-mode label at all — that's a triage gap, not a prep job. Route to `pm-triage` first; come back once it's labeled `hitl`.
- The operator only wants a review or only wants enrichment — that's `pm-review` / `pm-improve` directly. `pm-prep` is the whole interactive promotion pass, not one slice.

## The afk-readiness bar

This is the contract the whole skill turns on. An issue is afk-ready when an agent could pick it up cold and finish it without stopping to ask a human. Concretely, mirror what `pm-issue-to-pr` needs to call an issue "actionable":

- **AC is always present and testable (invariant).** pm-prep ALWAYS ensures a present, testable Acceptance Criteria checklist before promotion — it adds the section if absent, rewrites vague items into mechanically-verifiable ones, and NEVER promotes to afk without it. This is not advisory: the `hitl → afk` retag is backed by an `AFK_GATE_NO_AC` code gate (see Step 8) that hard-fails the promotion when `## Acceptance Criteria` is missing or placeholder-only.
- **Every required section is filled** with real content — not a bracketed placeholder, `TBD`/`TODO`, an empty `- [ ]`, or just the heading. (Required sections come from the issue's type tag in the templates manifest.)
- **Acceptance criteria are mechanically verifiable** — each item names a behavior a test or a reviewer could check pass/fail. Vague verbs with no target ("improve performance", "clean up the UX", "handle edge cases") fail the bar. The test: *would a tester know whether this passed?*
- **File targets are unambiguous** — if the work touches code, the issue points at the files/modules or describes them specifically enough that an agent isn't guessing which `foo.js` is meant.
- **The design path is chosen** — no "we could do A or B, depends what we want." If there were forks needing a preference, the operator's choice is now written down.
- **No dependency on a human-only or inaccessible step** — no "needs UX sign-off", "wait for the vendor", "verify on the physical device", "reconcile against the finance ledger" baked into the critical path. Watch for these disguised as verification steps: an acceptance criterion that reads like an automatable check ("confirm the output matches the records") but actually needs a human or a system the agent can't reach is still a human gate.
- **The premise holds against the code** — if the issue asserts a cause ("the filter isn't escaped", "there's no retry logic", "the function ignores X"), check it against the actual source *before* writing acceptance criteria around it. This is the highest-leverage check on the whole list, because a confident-but-wrong premise is the most dangerous thing you can hand an autonomous agent: it has no human to sanity-check it mid-run, so it will faithfully implement a fix for a bug that doesn't exist, or rebuild a feature that's already there. When the code contradicts the issue, that's a gap to resolve — not something to paper over by writing the issue's wrong assumption into the AC.

  A false premise does **not** automatically mean "hold" — it means "decide based on whether an agent can still finish unattended":
  - **Reproducible + behavioral AC → promote (with the premise corrected).** If the bug reproduces deterministically and you can write the acceptance criteria around the *observable behavior* ("delta-sync returns the project's real issue set for an apostrophe-containing name, asserted by a test") instead of the wrong mechanism, an agent can reproduce → diagnose → fix → verify on its own. Correct the premise in the body, frame the AC behaviorally, and it earns `afk`.
  - **Can't be reproduced without a human → hold.** If the real failure is intermittent, environment-specific, or nobody yet knows how to trigger it, then *diagnosis itself* is the human work — no behavioral AC can rescue it, because an agent can't even get to a red test. It stays `hitl` until someone pins down a deterministic repro.

If all of these hold, the issue earns `afk`. If even one *irreducibly* needs a human at execution time, it stays `hitl` — and the skill says exactly which one and why. That honesty is the point: a wrongly-promoted issue wastes an autonomous run and lands a bad PR.

## The prep pipeline (one issue)

Steps 1–6 are read-only and run without confirmation — they cost only tokens, and the operator needs the full picture before deciding. Steps 7–8 are the writes, each confirmed on its own.

### Step 1: Fetch the issue (live)

Read it fresh from the tracker — the same fetch `pm-review` uses (`linear issue view <ID> --json` via the GraphQL helper / `gh issue view <NUM> --repo <org/repo> --json ...`). Never prep from cache: the cache can carry a stale body or label set, and every decision here hinges on the *current* content.

If the tracker is unreachable, stop with a transport error. Do not prep from stale state.

### Step 2: Confirm it's a hitl issue

Check the labels:

- Has `hitl` → continue.
- Has `afk` already → nothing to promote. Tell the operator; offer a `pm-review` pass if they want to double-check it's actually ready.
- Has neither → this is a triage gap. Don't guess the mode. Route to `pm-triage` and stop.

### Step 3: Assess readiness — find the gaps

Run `pm-review` against the issue at its type tag. Capture which required sections are present / missing / placeholder-only, and whether the acceptance criteria are testable.

Then add the judgment layer `pm-review` deliberately won't: read the body and name *what specifically requires a human* — an unmade design decision, an ambiguous target, a verification that can't be automated. These are the items the interactive loop has to resolve. Hold them as the **gap list**.

Crucially, also **check the issue's premise against the actual code** here, while you have the repo open. If the issue claims a root cause or a missing capability, open the file it points at (or grep for it) and confirm the claim is true. A surprisin