Embed

---
name: human-plan
description: Fetch an issue tracker ticket and create an implementation plan
argument-hint: <ticket-key>
---

<!-- human:include launch-briefing -->

**Take ownership first.** Run `human assign <KEY>` (the ticket key this skill received) so the ticket records who is working it. It only sets ownership — no status change, so it never blocks on an approval gate. A failure here is not fatal: say so and carry on with the work.

# Implementation Plan Pipeline

Create an implementation plan using a 3-phase agent pipeline: draft, verify, finalize. No plan files are created — the plan lands on the tracker: as a separate engineering ticket's description (split topology: distinct PM and engineering trackers) or as a `[human:plan]` comment on the ticket itself (single-tracker topology).

## Phase 0: Inherit the chosen design

Run `human mockups chosen <KEY>` (the PM key this skill received). If it prints a path, read that HTML file — it is the human-selected design direction (the winning mockup) for this ticket. Treat it as authoritative UI/interaction context: the plan MUST build the UI to match it, and the planner prompt should carry that design as context. If it prints nothing, there is no chosen design; proceed normally.

## Phase 1: Draft Plan

Run the planner agent. It returns the plan as its output (no files written). The planner has no files yet to run `human review findings` against, so it depends on this prompt: if this skill's own prompt carries a launch briefing (the `## Be aware of these before you change anything` section), append it verbatim to the end of the Task prompt below, heading included:

```
Task(subagent_type="human-planner", model="opus", prompt="Create an implementation plan for ticket $ARGUMENTS. Return the complete plan as your output. Do not write any files.", run_in_background=false)
```

Wait for the planner agent to finish. Capture its output as `<PLAN_CONTENT>`.

## Phase 2: Verify (parallel)

Launch both verification agents **in a single message** so they run in parallel. Pass the plan content inline using markers. Each agent returns its report as output (no files written). Append the launch briefing here too, same as Phase 1:

```
Task(subagent_type="plan-verify-code", model="sonnet", prompt="Verify all code references in the following implementation plan against the actual codebase. Return your verification report as output. Do not write any files.\n\n---BEGIN PLAN---\n<PLAN_CONTENT>\n---END PLAN---", run_in_background=false)

Task(subagent_type="plan-verify-docs", model="sonnet", prompt="Verify all library, framework, and API assumptions in the following implementation plan against actual documentation and source. Return your verification report as output. Do not write any files.\n\n---BEGIN PLAN---\n<PLAN_CONTENT>\n---END PLAN---", run_in_background=false)
```

Wait for both agents to finish before proceeding.

## Phase 3: Finalize

Read both verification reports from the agent outputs.

If the verification reports found **no issues** (all OK, zero mismatches, zero missing):
- Proceed directly to attaching the plan (Phase 5).

If the verification reports found **issues** (mismatches, missing references, unaccounted dependents, deprecations, or unverifiable claims):
- Update `<PLAN_CONTENT>` to fix all verified issues:
  - Correct wrong signatures, types, or file paths
  - Add handling for every unaccounted dependent the code report lists, in the plan's `## Dependents` section AND in the `## Changes` step that must act on it
  - Replace deprecated APIs with their replacements
  - Mark unverifiable claims with "UNVERIFIED — confirm before implementing"

### Phase 3 gate: the dependents check

The code verification report carries a `**Dependents check: <pass|fail>**` line.
It is a gate, not a note — a plan that enumerates only the callers of a symbol
passes every other check while the change it describes ships broken.

- **pass** — continue.
- **fail** — repair the plan yourself: add the missing kinds and rows to its
  `## Dependents` section (each with the query you ran and its `file:line`
  result), and add to `## Changes` whatever the unaccounted dependents require.
  Then re-run **plan-verify-code alone** on the repaired plan (the same Task
  dispatch as Phase 2, briefing appended the same way; plan-verify-docs does
  not need to run again).

Repeat that repair-and-re-verify at most **twice**. If the check still fails
after the second re-verification, do not loop again and do not stop: mark each
still-failing kind in the plan's `## Dependents` section as
`unchecked: <kind> — <why>` and carry the same text into the `unchecked` field of
the `stage.planning` record below. An unchecked kind that is written down is what
the reviewer audits later; an unchecked kind left silent reads as "no dependents",
which is the failure this gate exists to catch. Never attach a plan whose
`## Dependents` section is absent altogether.

## Phase 3a: Already-implemented terminal (nothing to plan)

If the planner returned an `ALREADY IMPLEMENTED: <evidence>` verdict instead of a plan — exploration showed every acceptance criterion is already satisfied by code merged on `main` — the ticket's work has already shipped. Attaching a plan and posting `[human:plan-ready]` would advance the card and re-implement shipped code, so do NOT do that. Instead:

- Do NOT run the verification phases, attach any plan, or post `[human:plan-ready]`.
- Post the terminal `[human:nothing-to-do]` marker on the PM ticket, carrying the planner's evidence (name the merged PR/commit) and `reason=merged` — the reason is what the board labels, and `merged` is the only one it renders as "already shipped" (resolved), not red:

```bash
human marker post <PM_KEY> nothing-to-do --field "evidence=<the planner's ALREADY IMPLEMENTED evidence — merged PR/commit>" --field reason=merged
```

- STOP. Skip Phases 4-6 entirely. In board context this is mandatory: the workflow board's failure watcher treats `[human:nothing-to-do]` as a clean stop (resolved, no retry loop), whereas a missing `[human:plan-ready]` after a normal exit is misread as a crash and re-planned forever.

## Phase 3b: Decision-required terminal (up-front human fork)

If the planner returned a `DECISION REQUIRED:` verdict instead of a plan — the plan hinges on a product/UX or ambiguity fork only a human can settle — do NOT invent a plan and do NOT proceed to implementation with the decision baked in as a mid-run gate (that is the stranded-run failure this guards against). Surface the fork as an up-front `[human:options]` decision block on the PM ticket and STOP:

- Do NOT run the verification phases, attach any plan, or post `[human:plan-ready]`.
- Post the options block with stage `planning`, so the human's pick re-runs planning with the decision recorded. Map the verdict's first line to `context`, and each `N:` line to a `--field N=`:

```bash
human marker post <PM_KEY> options \
  --field stage=planning \
  --field context="<the DECISION REQUIRED one-liner>" \
  --field 1="<first option>" \
  --field 2="<second option>"
```

- STOP. Skip Phases 4-6 entirely. The board renders the options and waits; when the human picks, the daemon relaunches `/human-plan <PM_KEY>` with the choice injected as a `[human:option-chosen]` comment, and the planner then produces a fully autonomous, gate-free plan for that direction. In board context this is mandatory: posting the options block (not a plan-ready) is what lets planning pause cleanly instead of dispatching implementation into a decision no one is present to make.

## Phase 3c: Honor a sanctioned deferral (ship narrow + follow-on)

If the ticket carries a `[human:option-chosen]` comment whose chosen direction
is "ship the narrow slice now + follow-on ticket for the rest" (a choice a
person recorded — the planner itself no longer raises this as a delivery-order
fork, but a human can still pick it when answering the over-ask/contradiction
`DECISION REQUIRED:` that Phase 3b surfaces, per Autonomy contract rule 4), the
deferral is sanctioned. BEFORE attaching the narrow plan, spawn the durable
trace so the deferred criteria leave a real, linked ticket and the PM card is
marked shipped-partial. Run exactly once, naming every acceptance criterion you
are deferring:

```bash
human plan defer <PM_KEY> \
  --title "<short title for the follow-on ticket>" \
  --deferred "<first deferred acceptance criterion, verbatim>" \
  --deferred "<second deferred acceptance criterion, verbatim>"
```

This creates the follow-on ticket (linked related to <PM_KEY>), and posts the
`[human:shipped-partial]` marker naming the deferred criteria and the follow-on
key. Then continue to Phases 4-6 and attach the NARROW plan (the slice being
shipped now) as usual. Do NOT list the deferred criteria as work in the narrow
plan — they now live on the follow-on ticket.

## Phase 4: Confidence check

After finalizing the plan, review it yourself end-to-end:

1. For every API call, library function, or external integration in the plan, verify the function signatures, parameters, and return types against real documentation (use `WebFetch` or `WebSearch` if needed) or against the actual source code in the codebase.
2. For every file path, function name, type, and interface referenced in the plan, grep the codebase to confirm they exist and match the plan's assumptions.
3. Rate your confidence that the plan can be implemented as-is without the executor needing to make design decisions or discover missing information. If you are not fully confident:
   - Fix every gap, wrong assumption, or ambiguity in the plan now.
   - Re-verify the fixes against docs and code.
   - Repeat until you are confident the plan is correct and complete.
4. Scan the finalized plan for any mid-execution human gate — a step that waits for sign-off, approval, confirmation, or a user decision. There must be none. If the plan can only proceed past such a step with human input, that decision belonged up front: discard the plan and re-run planning so the planner emits the `DECISION REQUIRED:` terminal instead (Phase 3b).

Only proceed to ticket creation once you are confident the plan will work.

## Phase 5: Attach the plan and post the handoff (topology decides where)

Two writes, one step. Post the handoff as the **very next command** after the
plan — before any verification, before the state record, before reporting
anything. A step between them is a place a run can stop, and the handoff is
what finishes a planning run.

Run `human tracker topology`:

- **Split topology** — the output says `"topology": "split"` and its `engineering` entry names the tracker for the engineering ticket: create a separate engineering ticket there (steps below).
- **Single-tracker topology** — the output says `"topology": "single"` (no `engineering` entry): do NOT create a second ticket. The plan lives on the PM ticket itself as a `[human:plan]` comment (Phase 5b).

### Phase 5a: Split topology — create the engineering ticket

Confirm the plan has a `**PM ticket**:` line in its header referencing the original PM ticket key. If it is missing, add it before creating the engineering ticket so the executor can reference both tickets in commits.

Create the engineering ticket with the plan as the description. The ticket description **must be a 1:1 verbatim copy** of `<FINAL_PLAN_CONTENT>` — do not summarize, reformat, truncate, reorder, or rewrite any part of the plan. Every section, bullet, code block, and line must appear in the ticket exactly as in the final plan. Use a heredoc to preserve special characters and formatting:

```bash
human <tracker> issue create --project=<PROJECT> "Short title from plan" --description "$(cat <<'PLAN_EOF'
<FINAL_PLAN_CONTENT>
PLAN_EOF
)"
```

After creating the ticket, capture the returned engineering ticket key and update the ticket description so the `**Engineering ticket**:` line in the plan header contains the actual key (replacing `TBD`). This gives the executor both the PM and engineering ticket keys from the plan header so every commit can reference both.

Then fetch the ticket back and verify the description matches the updated plan content byte-for-byte. If it does not match, update the ticket until it does. Once it matches, post the handoff immediately as the last action of this phase:

```bash
human marker post <PM_KEY> plan-ready --field engineering=<ENG_KEY>
```

which renders as:

```
[human:plan-ready]
engineering: <ENG_KEY>
```

### Phase 5b: Single-tracker topology — attach the plan as a comment, then the handoff

Post the plan verbatim as a `[human:plan]` marker comment on the PM ticket (the ticket description stays product language; the plan is a stage artifact and lives in the comment stream), then post the handoff as the very next command — no step between them:

```bash
human marker post <PM_KEY> plan --body-file - <<'PLAN_EOF'
<FINAL_PLAN_CONTENT>
PLAN_EOF
human marker post <PM_KEY> plan-ready
```

In this topology the plan header needs no `**Engineering ticket**:` line, and commits reference only the PM key — no `engineering:` field on the handoff either; the board dispatches Implementation on the PM key itself. `<PM_KEY>` is the original PM ticket key from the plan's `**PM ticket**:` header. This mirrors the `[human:ready-for-review]` handoff that `human-executor` posts after implementation.

## Phase 6: Confirm both landed

Verify both writes landed before doing anything else — verification, state records, reporting. Which check verifies the plan write depends on topology, same as Phase 5:

- **Single-tracker topology** — the plan is the `[human:plan]` comment from Phase 5b:

  ```bash
  human plan show <PM_KEY>                      # must print the plan back
  human marker list <PM_KEY> | grep plan-ready  # must print the handoff
  ```

  Re-planning posts a new `[human:plan]` comment; the latest wins, never edit old ones.

- **Split topology** — there is no `[human:plan]` comment on the PM ticket; the plan is the engineering ticket's description, and `human plan show <PM_KEY>` finds nothing to print and fails. The verification that applies here is Phase 5a's byte-for-byte description check, already done before the handoff was posted:

  ```bash
  human marker list <PM_KEY> | grep plan-ready  # must print the handoff
  ```

**This marker is what finishes a planning run.** Attaching the plan in Phase 5
does not advance the card and neither does any state record — a plan comment is
content, not a stage signal. Post it yourself, every time. The daemon will
complete a handoff for a run that attached its plan and then died before
posting it, but that is a repair, not the protocol: it posts no
`engineering:` field, so it cannot cover split topology, and a run that could
have posted its own handoff and did not has left the trail saying a machine
finished its work.

## Retry budgets, flakes, and how this run may end

The board's planning stage runs this skill, so it must recover like every other stage rather than stopping at the first failure.

A verification pass or a tool call that fails is not automatically a failed plan. Re-run the failing step **alone** first: if it succeeds in isolation it is a flake — record it and retry without charging an attempt. Only a failure that reproduces identically twice is real. The budget is **3 real attempts**:

```bash
human state incr <PM_KEY> budget.planning.flakes      # vanished in isolation
human state incr <PM_KEY> budget.planning.attempts    # reproduced
human state get  <PM_KEY> budget.planning.attempts --default 0
```

Infrastructure trouble — a dead container, a network blip — is never a real attempt; it is a `retryable` ending, and the board relaunches the stage automatically rather than reddening the card.

Record the outcome so the board can tell a glitch from a blocker:

```bash
human state set <PM_KEY> stage.planning --json --body-file - <<'EOF'
{"exit":"done",
 "outcome":"<planned|nothing-to-do|decision-required>",
 "summary":"<one line>",
 "unchecked":"<dependent kinds whose query could not be run or resolved, and why — empty if none>",
 "evidence":"<the marker or ticket that carries the result>"}
EOF
```

**This state record is NOT the stage handoff, and writing it does not finish the
run.** The board never reads agent state to advance a card — only the
`[human:plan-ready]` marker does that. If you have written this and not yet
posted the marker, go back and post it now — that, not this record, is the last
act of a planning run.

<!-- human:include dependents -->

<!-- human:include exit-contract -->

## After completion

Before reporting, confirm the run actually ended: a planning run is finished
only once `[human:plan-ready]` is on the PM ticket (or a terminal marker from
Phase 3a/3b took its place). If it is not there, post it — do not report a plan
as ready on the strength of the plan comment alone.

Tell the user:
- A short summary of the plan (3-5 bullet points: what will change, key files, risks)
- Whether verification found issues and what was corrected
- Where the plan landed: the engineering ticket key (split topology) or the `[human:plan]` comment on the ticket (single-tracker topology)
- That `[human:plan-ready]` is posted, so the card can advance