(#$ISSUE_NUMBER)` (e.g., `fix(lobby): center QR code under room code (#15)`) - Branch is already pushable from the worktree ``` Skill({ skill: "ship" }) ``` Provide the title and `--body-file $PR_BODY_FILE` per `/ship`'s expected inputs. If `/ship` insists on writing its own commit message, let it — but verify the resulting PR body carries the rubric verification table. If not, append the rubric block as a follow-up PR comment via `gh pr comment`. Capture the PR URL from `/ship`'s output for the status JSON. ```bash rm -f "$PR_BODY_FILE" ``` Do NOT merge the PR. Do NOT commit anything outside `$WORKTREE_PATH`. ## Reporting back Write a status JSON to `$SESSION_DIR/issue-$ISSUE_NUMBER.json`. The PM depends on this file. ### DONE Use `jq -n --arg` (NOT heredoc interpolation) because rubric text in `summary` may contain `$(...)` or backticks. ```bash jq -n \ --arg issue "$ISSUE_NUMBER" \ --arg pr "<pr-url-from-ship>" \ --arg branch "$BRANCH" \ --arg qa "$QA_RESULT" \ --arg summary "<one-line summary>" \ --arg rubric_comment_id "$RUBRIC_COMMENT_ID" \ --arg worktree "$WORKTREE_PATH" \ '{ status: "DONE", issue: ($issue | tonumber), pr: $pr, branch: $branch, qa: $qa, rubric_comment_id: ($rubric_comment_id | tonumber), worktree: $worktree, summary: $summary }' > "$SESSION_DIR/issue-$ISSUE_NUMBER.json" # Append metrics row. Set ship_manual_edits=true if you had to manually edit # the PR body after /ship (e.g. to append the rubric verification block). emit_metrics "DONE" "$QA_RESULT" 0 0 "<pr-url-from-ship>" "$BRANCH" false "" cmux notify --title "#$ISSUE_NUMBER Done" --body "<summary>" 2>/dev/null || true ``` ### FAILED ```bash cat > "$SESSION_DIR/issue-$ISSUE_NUMBER.json" << EOF { "status": "FAILED", "issue": $ISSUE_NUMBER, "reason": "<specific reason>", "progress": "<what was completed>", "worktree": "$WORKTREE_PATH" } EOF emit_metrics "FAILED" "${QA_RESULT:-}" 0 0 "" "${BRANCH:-}" false "<specific reason>" cmux notify --title "#$ISSUE_NUMBER Failed" --body "<reason>" 2>/dev/null || true ``` ### NEEDS_CLARIFICATION (any phase — when the human can resolve via a short answer) ```bash jq -n \ --arg issue "$ISSUE_NUMBER" \ --arg progress "<what's done so far>" \ --argjson questions '["<q1>", "<q2>"]' \ '{status: "NEEDS_CLARIFICATION", issue: ($issue | tonumber), progress: $progress, questions: $questions}' \ > "$SESSION_DIR/issue-$ISSUE_NUMBER.json" emit_metrics "NEEDS_CLARIFICATION" "${QA_RESULT:-}" 0 1 "" "${BRANCH:-}" false "" cmux notify --title "#$ISSUE_NUMBER Needs Input" --body "<question summary>" 2>/dev/null || true ``` After writing NEEDS_CLARIFICATION, **wait** — the PM will send the human's answer via `cmux send` to your pane. Resume work when you receive it. **When to use NEEDS_CLARIFICATION:** any phase, any time the rubric, issue, or implementation reality reveals an ambiguity that needs a human decision. Examples: - Phase 2+ — requirements unclear mid-implementation - Phase 0a.1 — issue body and rubric Notes contradict each other on a small detail - Phase 4 (QA) — a rubric acceptance criterion is observably impossible (e.g. specifies a route that does not exist) and the right path forward is unclear **When NOT to use NEEDS_CLARIFICATION:** the rubric is malformed (missing required sections, Phase 0a.0) OR the rubric Summary topic does not match the issue Title (Phase 0a.2). Those are infrastructure failures, not ambiguity — use REGROOM_REQUIRED. ### REGROOM_REQUIRED (Phase 0a.0 or 0a.2 — never mid-implementation) Written from one of: - **Phase 0a.0** — rubric fetch+parse failed cleanly 3 times, rubric marker missing, or required sections missing. - **Phase 0a.2** — rubric Summary topic does not match issue Title topic. The workspace exits after writing the JSON — PM cannot send into a dead pane and must launch a NEW workspace with a new (re-groomed) rubric ID. </process> <rules> - Abort if bootstrap context (REPO, ISSUE_NUMBER, ISSUE_URL, SESSION_DIR, REPO_PATH, RUBRIC_COMMENT_ID) is missing — do NOT guess or fetch arbitrary issues - Load /browse first, always (Phase 0b) - Bash cwd does NOT persist — chain with `&&` or use absolute paths - All code changes go in `$WORKTREE_PATH`; never edit anything in `$REPO_PATH` directly - Branch from `main`, never any other branch - Run lint AND tsc --noEmit AND build AND vitest AND playwright in Phase 3 — all five - For UI changes, read `docs/DESIGN.md` BEFORE writing TSX/CSS — Stadium Energy is non-negotiable - Never run `bunx supabase db reset` or destructive Supabase commands while other dispatches may be running — the local DB is shared - Stage files surgically (`git add <files>`), never `git add -A` - Do not modify files outside the scope of this issue; no drive-by refactors - Do not merge the PR — only create it - ALWAYS write the status JSON when done — the PM depends on it - All temp/state goes under `/tmp/headball-pm-*` and `~/.headball-pm/`. Never write outside these prefixes (other projects' /pm copies use their own prefix) - You run interactively: you CAN pause at ANY phase with NEEDS_CLARIFICATION; never guess on unclear requirements - Phase 0a.2 alignment guard is mandatory — if rubric Summary topic ≠ issue Title topic → REGROOM_REQUIRED, exit. Disclaiming the mismatch in the PR body is not a substitute for stopping - When fetching any GitHub API resource, NEVER combine `gh api ... --jq` with manual fallback parsing. On parse error, retry the FETCH cleanly via `gh api ... > file && jq -r .body file`. After 3 failures → REGROOM_REQUIRED - The rubric is the QA checklist. Silent-PASS is banned — every claimed `[x]` needs an evidence note </rules>

`, read that section and compare. If Figma access errors (URL 404, MCP not installed): record `visual_comparison: unavailable — ` and proceed. **If QA fails**: fix the code and re-run the affected check. Repeat until QA passes or you determine the issue is a documented limitation. Record one of: - `QA_RESULT=PASS` — every rubric item ✓ with evidence. `$RUBRIC_CHECK` contains only `[x]` lines. - `QA_RESULT=FAIL` — one or more `[ ]` with Expected/Observed. - `QA_RESULT=SKIPPED` — infrastructure failure (dev server, /browse unavailable). - `QA_RESULT=N/A` — rubric marks change non-UI (`UI_CHANGE=no` AND all States=N/A). **Silent-PASS is banned.** If you can't produce at least one `[x]` line with an evidence note, the result is NOT PASS. It's SKIPPED (infra) or FAIL (intent not verified). Hand `$RUBRIC_CHECK` to Phase 5. ### Always tear down ```bash kill "$DEV_PID" 2>/dev/null lsof -ti tcp:$QA_PORT | xargs -r kill 2>/dev/null ``` Close any browser surfaces opened by `/browse` per its skill instructions. Leave the workspace open — PM closes it after you report DONE. ## Phase 4.5: Self-retro — complain about upstream Before shipping, write a structured retrospective on what made this dispatch harder than it should have been. The PM aggregates these via `/pm retro` to find the highest-leverage edits to the Analyst / Rubric Writer prompts. **What to record (closed category enum):** | Category | Meaning | |----------|---------| | `rubric_unclear` | Acceptance criterion ambiguous, vague, or undefined | | `rubric_wrong` | Rubric contradicts the issue body or current codebase | | `rubric_missing_state` | A state you had to verify wasn't covered (loading/empty/error) | | `missing_context` | Issue dependencies, related code, or constraints not surfaced | | `bootstrap_malformed` | pm dispatch payload missing or wrong | | `scope_creep` | Rubric implied work beyond what the issue asked for | | `figma_unreachable` | Visual reference URL was 404, gated, or wrong frame | | `wrong_skill_routed` | Bootstrap implied `/investigate` but issue was a feat (or vice versa) | | `design_md_missing` | Rubric required UI work but did not cite `docs/DESIGN.md` section | | `db_collision` | Parallel pm-dev session corrupted shared Supabase data mid-run | **Severity:** - `blocker` — caused REGROOM_REQUIRED, NEEDS_CLARIFICATION, or FAILED - `friction` — slowed the dispatch but didn't stop it (forced a guess, retry, or extra round-trip) - `minor` — nitpick; would have been smoother if fixed **ONLY record upstream problems** — bugs in the codebase, your own mistakes, and infrastructure flakes (network, server crashes) do NOT belong here. The signal is "what should the orchestrator have given me that it didn't?" If nothing went wrong upstream, leave `$RETRO_FILE` as the empty array `[]`. ```bash # Append a complaint object. Repeat for each distinct issue. TMP=$(mktemp /tmp/headball-pm-retro-XXXXXXXX.json) jq '. += [{ category: "rubric_unclear", severity: "friction", phase: "phase2", description: "", what_dev_did: "", suggested_fix: "" }]' "$RETRO_FILE" > "$TMP" && mv "$TMP" "$RETRO_FILE" ``` `$RETRO_FILE` is read by `emit_metrics` in the Reporting back step and embedded in the metrics row's `dev_retro` field. Each `friction`-severity entry shaves 0.05 off `dispatch_score`; `blocker` and `minor` don't penalize. ## Phase 5: Commit + PR via /ship `/ship` is the gstack skill that handles commit, push, and PR creation. Hand it the rubric verification block so the PR body carries traceability. **Pre-/ship: stage your changes** ```bash cd "$WORKTREE_PATH" && git add ``` Do NOT use `git add -A` or `git add .` — surgical staging only. **Build the PR body file** — shell-safe pattern: write your own prose with normal interpolation, then `printf '%s\n' "$RUBRIC_CHECK"` (literal — never `echo` or heredoc-interpolate, since rubric text may contain `$(...)`, backticks, or `${VAR}`). ```bash PR_BODY_FILE=$(mktemp /tmp/headball-pm-pr-body-XXXXXXXX.md) # Your own prose first — fill in and . cat > "$PR_BODY_FILE" < Fixes #$ISSUE_NUMBER ## Changes - ## Rubric verification EOF # Rubric check — literal write, no shell interpolation of rubric content. if [ -n "$RUBRIC_CHECK" ]; then printf '%s\n' "$RUBRIC_CHECK" >> "$PR_BODY_FILE" printf '\nGroomed rubric: https://github.com/%s/issues/%s#issuecomment-%s\n' "$REPO" "$ISSUE_NUMBER" "$RUBRIC_COMMENT_ID" >> "$PR_BODY_FILE" else printf '\nQA Result: %s\n' "$QA_RESULT" >> "$PR_BODY_FILE" fi printf '\nGenerated with [Claude Code](https://claude.com/claude-code)\n' >> "$PR_BODY_FILE" cat "$PR_BODY_FILE" ``` **Now invoke /ship.** Hand it: - The pre-built PR body file path (`$PR_BODY_FILE`) - Suggested PR title: `(): (#$ISSUE_NUMBER)` (e.g., `fix(lobby): center QR code under room code (#15)`) - Branch is already pushable from the worktree ``` Skill({ skill: "ship" }) ``` Provide the title and `--body-file $PR_BODY_FILE` per `/ship`'s expected inputs. If `/ship` insists on writing its own commit message, let it — but verify the resulting PR body carries the rubric verification table. If not, append the rubric block as a follow-up PR comment via `gh pr comment`. Capture the PR URL from `/ship`'s output for the status JSON. ```bash rm -f "$PR_BODY_FILE" ``` Do NOT merge the PR. Do NOT commit anything outside `$WORKTREE_PATH`. ## Reporting back Write a status JSON to `$SESSION_DIR/issue-$ISSUE_NUMBER.json`. The PM depends on this file. ### DONE Use `jq -n --arg` (NOT heredoc interpolation) because rubric text in `summary` may contain `$(...)` or backticks. ```bash jq -n \ --arg issue "$ISSUE_NUMBER" \ --arg pr "<pr-url-from-ship>" \ --arg branch "$BRANCH" \ --arg qa "$QA_RESULT" \ --arg summary "<one-line summary>" \ --arg rubric_comment_id "$RUBRIC_COMMENT_ID" \ --arg worktree "$WORKTREE_PATH" \ '{ status: "DONE", issue: ($issue | tonumber), pr: $pr, branch: $branch, qa: $qa, rubric_comment_id: ($rubric_comment_id | tonumber), worktree: $worktree, summary: $summary }' > "$SESSION_DIR/issue-$ISSUE_NUMBER.json" # Append metrics row. Set ship_manual_edits=true if you had to manually edit # the PR body after /ship (e.g. to append the rubric verification block). emit_metrics "DONE" "$QA_RESULT" 0 0 "<pr-url-from-ship>" "$BRANCH" false "" cmux notify --title "#$ISSUE_NUMBER Done" --body "<summary>" 2>/dev/null || true ``` ### FAILED ```bash cat > "$SESSION_DIR/issue-$ISSUE_NUMBER.json" << EOF { "status": "FAILED", "issue": $ISSUE_NUMBER, "reason": "<specific reason>", "progress": "<what was completed>", "worktree": "$WORKTREE_PATH" } EOF emit_metrics "FAILED" "${QA_RESULT:-}" 0 0 "" "${BRANCH:-}" false "<specific reason>" cmux notify --title "#$ISSUE_NUMBER Failed" --body "<reason>" 2>/dev/null || true ``` ### NEEDS_CLARIFICATION (any phase — when the human can resolve via a short answer) ```bash jq -n \ --arg issue "$ISSUE_NUMBER" \ --arg progress "<what's done so far>" \ --argjson questions '["<q1>", "<q2>"]' \ '{status: "NEEDS_CLARIFICATION", issue: ($issue | tonumber), progress: $progress, questions: $questions}' \ > "$SESSION_DIR/issue-$ISSUE_NUMBER.json" emit_metrics "NEEDS_CLARIFICATION" "${QA_RESULT:-}" 0 1 "" "${BRANCH:-}" false "" cmux notify --title "#$ISSUE_NUMBER Needs Input" --body "<question summary>" 2>/dev/null || true ``` After writing NEEDS_CLARIFICATION, **wait** — the PM will send the human's answer via `cmux send` to your pane. Resume work when you receive it. **When to use NEEDS_CLARIFICATION:** any phase, any time the rubric, issue, or implementation reality reveals an ambiguity that needs a human decision. Examples: - Phase 2+ — requirements unclear mid-implementation - Phase 0a.1 — issue body and rubric Notes contradict each other on a small detail - Phase 4 (QA) — a rubric acceptance criterion is observably impossible (e.g. specifies a route that does not exist) and the right path forward is unclear **When NOT to use NEEDS_CLARIFICATION:** the rubric is malformed (missing required sections, Phase 0a.0) OR the rubric Summary topic does not match the issue Title (Phase 0a.2). Those are infrastructure failures, not ambiguity — use REGROOM_REQUIRED. ### REGROOM_REQUIRED (Phase 0a.0 or 0a.2 — never mid-implementation) Written from one of: - **Phase 0a.0** — rubric fetch+parse failed cleanly 3 times, rubric marker missing, or required sections missing. - **Phase 0a.2** — rubric Summary topic does not match issue Title topic. The workspace exits after writing the JSON — PM cannot send into a dead pane and must launch a NEW workspace with a new (re-groomed) rubric ID. </process> <rules> - Abort if bootstrap context (REPO, ISSUE_NUMBER, ISSUE_URL, SESSION_DIR, REPO_PATH, RUBRIC_COMMENT_ID) is missing — do NOT guess or fetch arbitrary issues - Load /browse first, always (Phase 0b) - Bash cwd does NOT persist — chain with `&&` or use absolute paths - All code changes go in `$WORKTREE_PATH`; never edit anything in `$REPO_PATH` directly - Branch from `main`, never any other branch - Run lint AND tsc --noEmit AND build AND vitest AND playwright in Phase 3 — all five - For UI changes, read `docs/DESIGN.md` BEFORE writing TSX/CSS — Stadium Energy is non-negotiable - Never run `bunx supabase db reset` or destructive Supabase commands while other dispatches may be running — the local DB is shared - Stage files surgically (`git add <files>`), never `git add -A` - Do not modify files outside the scope of this issue; no drive-by refactors - Do not merge the PR — only create it - ALWAYS write the status JSON when done — the PM depends on it - All temp/state goes under `/tmp/headball-pm-*` and `~/.headball-pm/`. Never write outside these prefixes (other projects' /pm copies use their own prefix) - You run interactively: you CAN pause at ANY phase with NEEDS_CLARIFICATION; never guess on unclear requirements - Phase 0a.2 alignment guard is mandatory — if rubric Summary topic ≠ issue Title topic → REGROOM_REQUIRED, exit. Disclaiming the mismatch in the PR body is not a substitute for stopping - When fetching any GitHub API resource, NEVER combine `gh api ... --jq` with manual fallback parsing. On parse error, retry the FETCH cleanly via `gh api ... > file && jq -r .body file`. After 3 failures → REGROOM_REQUIRED - The rubric is the QA checklist. Silent-PASS is banned — every claimed `[x]` needs an evidence note </rules>