refine

# /swarm:refine

Recursive refinement on an existing branch and pull request. Skips Research/Converge/Approve/Execute — the team enters at Review, then Refine, then Deliver.

Pass outcomes inline (`/swarm:refine <outcomes>`) or run without arguments to be prompted.

Read `${CLAUDE_PLUGIN_ROOT}/commands/launch.md` for Step 0 (pre-flight), Step 1 (hard rules), and Steps 8a–8e (team creation, member spawning, pulse setup). This command replaces Steps 2–7 and overrides Step 8f.

**No lead research unless enabled.** The pre-flight reads below are housekeeping, not research — they run unconditionally (analogous to launch.md's ship-definition detection). All other research is delegated to teammates.

## Settings

- **Mode:** Code
- **Outcomes question:** "What outcomes was this branch/PR supposed to achieve? (Describe what was meant to be working differently or better — the team will refine the work against these outcomes.)"
- **Cost tier:** Ultra
- **Lead research:** No
- **Roster (fixed):** Principal Engineer (facilitator), Correctness Reviewer, Outcomes Reviewer, Regression Reviewer

## User-Provided Context

$ARGUMENTS

## Workflow

1. **Pre-flight reads.** Run via Bash, capture each output as a raw string. Use the exact abort messages below — they are the user's only signal that something is wrong, so consistency matters across invocations.

   - `git rev-parse --is-inside-work-tree` — if not in a git repo, abort with: `Not in a git repository. /swarm:refine works on a branch and pull request.`
   - `git branch --show-current` — capture. If empty (detached HEAD), abort with: `Cannot run /swarm:refine in detached HEAD state. Run "git checkout <branch-name>" to switch to a branch first.` If equal to the repo's default branch (resolved via `git symbolic-ref refs/remotes/origin/HEAD --short 2>/dev/null` then stripping `origin/`), abort with: `Cannot refine the default branch directly. Switch to a feature branch.`
   - `gh pr view --json title,body,baseRefName,url 2>/dev/null` — capture PR data if present. Extract `baseRefName` for the diff base. If no PR exists, fall back to the repo's default branch resolved earlier via `git symbolic-ref refs/remotes/origin/HEAD --short 2>/dev/null` (stripped of `origin/`) — `master`, `develop`, or whatever the repo actually uses. Do not hardcode `main`. If `git symbolic-ref` itself returns nothing (no `origin/HEAD` set), abort with: `Cannot determine the default branch — origin/HEAD is not set. Run "git remote set-head origin -a" or open a PR with the correct base before re-running /swarm:refine.` Surface the fallback (whichever branch was resolved) explicitly in the Step 7 confirmation summary so the user can correct the base before launch.
   - `git diff <base>...HEAD` — capture. If empty (HEAD == base), abort with: `No changes detected between <branch> and <base>. Nothing to refine. If this is unexpected, verify the diff base is correct.` (substitute the actual branch and base names).
   - `git diff --stat <base>...HEAD | tail -1` — capture the one-line diff stat (e.g., `12 files changed, 340 insertions(+), 45 deletions(-)`) for the Step 3 confirmation summary. If the diff is empty this is moot — the empty-diff abort above fires first.

2. **Outcomes.** If User-Provided Context is non-empty, use as outcomes. Otherwise ask the outcomes question (plain text, not AskUserQuestion). Do NOT echo the outcomes back verbatim — run the outcome reflection instead: You MUST use the **Skill** tool to invoke `swarm:reflect-outcome` with the user's exact words as `args`, and do not author its wording yourself. If it returns `NO FORK` (the common case), show nothing — no echo, no confirmation beat — and carry the outcome into the Step 3 plan-confirmation summary, which already displays the outcomes verbatim (that is where the user sees their words carried forward). If it returns a ready-to-render fork, present it with AskUserQuestion exactly as returned — transport it, do not reword the question or labels, and do not add a third option (the fork is sealed at exactly two) — then resolve the user's pick per the skill (Option A keeps the wording; Option B re-authors into a new verbatim, which loops back through this Step 2 reflection). Store no separate supplement. The user's verbatim words are captured for the briefs (launch.md verbatim-capture rule). Framing-help (`swarm:refine-outcomes`) is offered as a third option on the Step 3 plan-confirm below — never here — so a reflection fork and the framing offer never stack in the same beat.

3. **Confirmation.** Present the team plan summary as a blockquote (matching launch.md Step 7's format):

   > **Team Plan**
   >
   > **Mode:** Code
   >
   > **Outcomes:**
   > [confirmed outcomes verbatim]
   >
   > **Scope:**
   > [only if the outcome reflection fired a fork AND the user chose Option A (keep their wording) — show "\<their word> specifically". Omit entirely otherwise — every NO-FORK run and after an Option B re-author.]
   >
   > **Branch under review:** [current branch]
   >
   > **Diff base:** [PR base if found, otherwise the resolved default branch — e.g., `main`, `master`, `develop`]
   >
   > **PR:** [PR URL if found, otherwise `(no open PR detected)`]
   >
   > **Changes:** [the one-line diff stat captured in Step 1, e.g., `12 files changed, 340 insertions(+), 45 deletions(-)`]
   >
   > **Team:**
   > 1. Team lead — (main session) [research: no]
   > 2. Principal Engineer — Socratic facilitator, read-only
   > 3. Correctness Reviewer — verifies logic correctness, edge cases, test coverage
   > 4. Outcomes Reviewer — verifies the work delivers the stated outcomes
   > 5. Regression Reviewer — verifies adjacent code and in-repo automation are not broken
   >
   > **Cost tier:** Ultra
   >
   > **Phase arc:** Review → Refine → Deliver
   >
   > **Ship definition:** [contents of `.claude/swarm-ship.md` if present, otherwise auto-detect per launch.md Step 8f rules]
   >
   > **Rules:** Active

   If the diff base is