/dotask — task doc → open PR, without dropping it halfway

/dotask <slug|id> [--sync]    run until the PR is open; --sync pushes to the tracker at the end
/dotask <slug|id> --qa        same, then run /qa on the PR diff and comment the verdict
/dotask <slug|id> --status    only report where the task is (dispatches nothing)

Read ../orchestrate/CORE.md before any step. This skill reimplements nothing: it resolves the task, dispatches through the canonical mechanism (worktree + tmux session, CORE §2, the execute flow) and watches until the PR opens. For several tasks at once, use /orchestrate.

Step 0 — Resolve the task

1. Adapter (CORE §1). <id> can be a slug (file <vault.cards>/<slug>.md) or a tracker id (search the task docs' front matter). No doc → if the adapter has a backlog reader (backlog.reader), read the card and create a minimal doc in the plan format before continuing; no card either → stop and suggest /plan. A doc with type: qa (or a qa-* slug whose scope is testing, not building): the task IS a QA run — invoke the qa skill and follow its flow (it has its own dispatch, watcher and report; the manifest is its own). The end of that route is the report, not a PR — the endings of Step 4 do not apply.
2. Four eligibility filters (CORE §1): status, layer, dependencies (depends_on open → stop and report the chain) and reality (already done?).

3. Deterministic pre-flight, before dispatching anything:

   python3 <skills>/orchestrate/scripts/doctor.py <repo>

   Contract: exit 1 = critical → do NOT dispatch (report what it flagged and stop); exit 0 = go on, carrying the warnings to the report. It covers execute Step 0 (clean main checkout, base == origin) and the health of <gh>.

Step 1 — Route

CORE §2. The task needs the scarce_resource → not a case for autonomous /dotask: say so and run it inline with the human (the execute flow). Inline keeps the manifest (Step 2, worktree column = main checkout), the acceptance criteria as DoD, the detour rule, the pre-PR review and Step 5 — it only skips the tmux dispatch and the watcher. Kitchen route → continue.

Step 2 — Manifest BEFORE dispatch

A batch of one is still a batch: write <vault.plans>/YYYY-MM-DD-<slug>-manifest.md (CORE §7) with its single row at ⏸ queued. Without a manifest /harvest can never clean this worktree (CORE §7 boundary) and a crash becomes a mystery with no record.

Step 3 — Dispatch

The canonical CORE §2 command: worktree + branch through execute Step 2 — when the id IS the slug (task born in /plan, no tracker card): branch = <type>/<slug>, without repeating the slug — and record the chosen branch in the doc's branch: field. A .kitchen/done left in a reused worktree by an earlier attempt must be removed first — the watcher would read it as "done" at once. Then .kitchen/prompt.md, session kitchen-<slug>, --strict-mcp-config. --model comes from the doc's model_exec (the doc wins over the adapter's model_by_size; absent in both = account default). Besides the standard content, the prompt carries FOUR rules of this skill:

1. Acceptance criteria are the DoD. The PR only opens with every criterion of the doc checked (- [x]) or with the unchecked one justified in the PR body.
2. The detour rule (section below), verbatim.
3. Independent pre-PR review. Between the gates (execute Step 8) and the PR (Step 11), dispatch an in-session reviewer subagent with the doc's model_review, giving it the diff (git diff <base>...HEAD) + the acceptance criteria. It returns APPROVED or a list of problems; fix and repeat (≤3 rounds). No APPROVED by the 3rd → the stop protocol of execute Step 9 (⏳ + reason). The review verdict goes in the PR body.
4. Doc without a tracker id = the card does not exist yet. The status lives in the doc's front matter (edit status: there); do not call the tracker — there is nothing to update. The card is born at --sync, if requested.

Update the manifest: 🔄 running — and record the dispatch instant (dispatched: YYYY-MM-DD HH:MM in the manifest's front matter; created: only has the date, and a date does not tell two attempts on the same day apart). Step 4 needs it to not confuse this batch's PR with a PR from an earlier attempt of the same task.

Check the boot before arming the watcher: ~30 s after dispatch, tmux capture-pane -p -t '=kitchen-<slug>:' (trailing colon — CORE §2). Two possible dialogs: the Bypass Permissions acceptance (first time on the machine) and folder trust (attach, accept, detach). Without this check the watcher would watch a stuck dialog thinking it is work.

The detour rule — a bug midway does NOT stop the task

If the agent (or you) finds a bug/unexpected behaviour outside the scope of the acceptance criteria during execution:

1. Do not fix it. Out of scope is out of scope.
2. Record it via /plan --problem (template Symptom / Origin / How to reproduce / Expected vs. actual): a new doc with file:line evidence and found_during: <slug of this task>.
3. Note it in the PR: the body lists "found along the way: <recorded slug(s)>".
4. Carry on with the original task. The record costs minutes; the detour would cost the PR.

Only exception: the bug prevents an acceptance criterion (the task cannot close on top of it). That is a real blocker: record the problem the same way AND apply the execute Step 9 stop protocol (⏳ waiting on human + reason on the manifest).

Step 4 — Watch until the PR (without burning tokens on polling)

The watcher is a background process, not an agent:

python3 <skills>/orchestrate/scripts/watch.py <worktree> <slug> --manifest <manifest>

Exit codes: 0 done (.kitchen/done or ✅ on the row) · 2 crash (session dead, no done) · 3 ⏳ waiting on human · 4 manifest missing (the ⏳/🚫 triggers would be blind — fix the path) · 5 🚫 aborted · 6 timeout with the session alive. It logs one line per iteration (alive/done/state).

A query that errors is not an answer. Network failure, <gh> exit ≠ 0, timeout, 401, empty JSON because of an error — all INCONCLUSIVE, never "no PR yet". Conclude nothing from a failed check: do not rewrite the manifest, do not give up — try again. A network blip read as a verdict is the easiest way to declare failure on work that was already done.

When the watcher exits, decide in this order:

• exit 0 → the agent closed: confirm the PR (<gh> pr view <branch> --json url,state,createdAt), reap the session (hibernation, CORE §2) and go to Step 5. The PR only counts if createdAt ≥ the manifest's dispatched (with ~120 s slack for clocks/latency): branches are reused across attempts, and an already merged PR from an earlier attempt at the SAME task makes the watcher cry a false ✅. createdAt older than the dispatch = another batch's PR → treat as "no PR" and keep watching. ✅/done without a verifiable PR (or only an old one) is an anomaly: flag it.
• exit 3 (⏳) → take it to the human NOW (reason + how to attach: tmux attach -t '=kitchen-<slug>'). Resolved in the agent's conversation → rewrite the row to 🔄 running yourself (you are the waiter; without it the watcher wakes up on the same ⏳ and alerts in a loop — CORE §7, ⏳→🔄) and watch again.
• exit 2 (crash) → CORE §7 reconciliation (inspect git -C <worktree> status/log, rewrite .kitchen/prompt.md with the partial state, recreate the session) and watch again. Never re-dispatch the original prompt on top of partial work.
• exit 5 (🚫) → stop and report the reason; cleanup is the waiter's role (CORE §11).
• exit 6 (timeout) → attach and look; do not conclude anything from the clock alone.

/dotask only ends successfully when the PR is open. The only other endings are 🚫 and a ⏳ the human decided not to resolve now.

Step 5 — Close

1. Manifest: ✅ PR + number + session id (the agent already wrote it in execute Step 12; check).
2. Report: PR, commits, acceptance criteria checked (and what was justified), detours recorded (/plan --problem → slugs).
3. --sync (optional tracker integration, see docs/integrations.md): dry-run first, always, and confirm the dry-run targets exactly 1 doc and the right card (matching by name can grab the wrong card). Commenting on an existing, confirmed card → apply. Creating a card → show it and wait for the human's OK.
4. --qa: the PR opened → run the QA pass on the diff BEFORE the final report. Invoke qa with target #<PR>: depth smoke (standard if the doc has size: L|XL), anchor oracle = the doc's acceptance criteria. At the end: <gh> pr comment <PR> --body with the verdict + findings (1 line each) + link to the report — the ONLY write of /qa on a PR, and a failing verdict does NOT close the PR: it is information for the human review.
5. Remind: merging, closing the card and removing the worktree are the human's + /harvest.

--status — read only

1. Newest manifest of the slug: glob <vault.plans>/*-<slug>-manifest.md (there may be several, from past attempts — take the newest).
2. One verdict line per source: manifest row (state) · tmux has-session -t '=kitchen-<slug>' (process alive?) · .kitchen/done (hibernated?) · <gh> pr view <branch> (PR — same createdAt rule as Step 4).
3. No manifest at all → "never dispatched; use /dotask <slug>".

Zero writes — touches no manifest, doc, session or tracker.

This skill does NOT

• Sequence a backlog — several tasks is /orchestrate.
• Fix out-of-scope bugs (detour rule: record and carry on).
• Merge, close cards or remove worktrees (/harvest after the merge).
• Push to a tracker without --sync, and never CREATE a card there without the human's OK.
• Watch with an agent in a loop — the watcher is a process; tokens are spent on work.