/refine

description: Run recursive refinement on the current branch and PR
argument-hint: <outcomes>
disable-model-invocation: true

/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 (invoke `swarm:workflow-rules` — the governance spec), Steps 8a–8e (team creation, member spawning, pulse setup), and the **Universal rules that apply across all modes** in Step 8f — especially the governance spec's **Live-team gate prompts** rule (the AFK-timeout / durable plain-text-restatement recovery), which governs this command's decision gates (Finish, ship-approval) too. This command replaces Steps 2–7 and overrides Step 8f's phase arc — not those universal rules.

**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 per the governance spec's transport contract (the fork is sealed at exactly two options) — 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).

3. **Confirmation.** Render the **Plan gate** (refine variant) with AskUserQuestion. Both modal carriers project from its catalog entry:

• **Question digest slots** (order fixed by the catalog — delta first): the diff base (the correctness pivot at this gate — silently inferred, not changeable from this prompt); the PR state (the PR URL, or `(no open PR detected)`); when the diff base is the default-branch fallback (no PR detected), this warning inline: `no PR detected — diff base falls back to the repo's default branch (<resolved-default>). Verify before launch.`; the compressed outcomes line (outcomes are adjustable at this gate via Step 2 re-entry); the scope line only if the reflection fork kept a pin (Option A — "\<their word> specifically"; omit entirely otherwise); the branch under review; the one-line diff stat captured in Step 1.
• **Preview** (same markdown on both options — the fixed fields live here, not in the digest, because they cannot change at this gate):

> **Team Plan** > > **Mode:** Code > > **Outcomes:** > [confirmed outcomes verbatim] > > **Team:** > 1. Team lead — (main session) [research: no] > 2. Principal Engineer — Socratic