--- name: finish description: Finish a Linear issue — check off requirements, add completion comment, commit/push, mark Ready For Release. Use when the user says 'finish issue', 'done with this issue', 'complete PL-XX', or invokes /finish. --- # Finish Issue Automates the post-completion workflow for a Linear issue using the `linear-cli` CLI. The mechanical steps (worktree-mode detection, issue-ID resolution, Linear posts, git commit/push) are delegated to scripts in `~/.claude/scripts/`; this skill is the orchestrator + LLM-judgment surface (reading the description, composing the completion comment). ## Arguments - Issue identifier (e.g., `PL-12`) — optional, auto-detected from branch/commit - `no push` / `don't push` / `skip push` — optional, skips the git push step (commit still happens) - `merge` — only meaningful inside a `/start wt` worktree. **Default when in a worktree.** Merge the worktree branch back into its recorded source branch, then remove the worktree. - `pr` — open a pull request for the current branch (works from **any** branch). Inside a `/start wt` worktree the base is the recorded source branch and the worktree is left in place; otherwise the base is the repo's GitHub default branch (in-place — no worktree touched). Optionally apply labels with `with label X` / `label X, Y`. The issue stays `In Progress` (the PR is open, not yet shipped). Examples: `/finish`, `/finish PL-12`, `/finish no push`, `/finish PL-12 no push`, `/finish merge`, `/finish pr PL-12`, `/finish pr with label pr-deploy` ## Invariant **`pnpm check` must pass before committing or pushing code.** Check failures are always CRITICAL — never "pre-existing", never "out of scope", never deferred. Fix them before proceeding. Turborepo caching makes repeated runs cheap. ## Workflow ### Preflight: Exit Plan Mode If Active If the session is in plan mode when `/finish` is invoked, call `ExitPlanMode` **before any other step**. Every step from Step 0 onward needs Bash, Write, or Edit — all blocked in plan mode — so `finish-detect-mode.sh` would fail on its first call otherwise. **Detection.** Use the harness's plan-mode indicator visible at skill entry (the same signal that was gating tool calls just before this skill loaded). If that indicator is ambiguous or unavailable, attempt Step 0; if `finish-detect-mode.sh` fails with a plan-mode block, return here, call `ExitPlanMode`, then retry Step 0. Do NOT speculatively call `ExitPlanMode` when plan mode is not active — it raises a spurious approval prompt the user must dismiss. **Plan body.** Pass a one-line plan summarizing what `/finish` is about to do for the resolved issue. There is nothing to design — `/finish` is a fixed mechanical workflow — but `ExitPlanMode` is the only way to leave plan mode and it requires a plan body. For the `` substitution: only inline a user-supplied token if it matches `^[A-Z]+-[0-9]+$` (case-insensitive, uppercase it before substituting); otherwise use `the current branch's issue`. This keeps malformed tokens (e.g., `PL13`, stray `merge`/`pr` keywords) out of the plan body and out of any rejection-terminator that echoes the same value. - Approved by the user: proceed to Step 0. - Rejected by the user: proceed to the rejection terminator below. - Tool-error / harness failure (not a user rejection — the tool itself returns an error, or the harness reports `ExitPlanMode` failed for a non-user-cancel reason): surface the error verbatim and stop with `BLOCKED-ON-REVIEW: — ExitPlanMode failed: . No state change.` Do NOT continue to Step 0; plan mode is still active and Step 0 will compound the failure. **On user rejection** via the approval UI, treat as an abort and stop with: ```text BLOCKED-ON-REVIEW: — user rejected /finish at the plan-mode preflight. No state change. ``` Do not retry, do not re-prompt, do not run any subsequent step. **Skip this preflight only when plan mode is NOT active** — `/finish` is normally invoked from a non-plan session after `/start` or manual development, in which case this section is a no-op. ### Step 0: Detect Worktree Mode Normalize the user's args before calling the script: - Look for `merge` and `pr` tokens (case-insensitive, position-agnostic) — pass through whichever is present (if both, the script errors). - Look for `no push` / `don't push` / `skip push` — translate to `--no-push` for the script. - Look for label requests (`with label X`, `label X, Y`, `--label X`) — collect them into a list and **carry it forward to Step 9** (pr mode only). Labels are NOT passed to the script — its arg contract is `merge|pr|--no-push` only. **If labels were requested but the resolved `ACTION` is not `pr`** (i.e., `merge` or the standard flow), labels have no PR to attach to — warn the user once (`Labels apply only to /finish pr; ignoring: .`) rather than silently dropping them. ```bash ~/.claude/scripts/finish-detect-mode.sh [merge|pr] [--no-push] ``` The script probes worktree state, validates incompatible argument combinations, and emits these `KEY=value` lines on stdout: `ACTION`, `SOURCE_BRANCH`, `WORKTREE_BRANCH`, `WT_DIR`, `REPO_ROOT`, `NO_PUSH`, plus `CORRUPTION` and `IDENTITY_SOURCE` (and, only on exit 4, `CORRUPTION_REASON` / `EXPECTED_BRANCH` / `EXPECTED_BASELINE` / `EXPECTED_SOURCE_BRANCH` — see exit 4 above and Step 0.5). **Read those values and carry them forward** — Step 9 substitutes them into bash commands as literal strings (each Bash tool call is a fresh shell). **Exit codes:** - 1 — incompatible args (e.g., `merge` + `pr`, or `pr` + `no push`). Surface the error and stop. - 2 — `merge` requested outside a `/start wt` worktree. Surface and stop. (`pr` is **not** rejected here — it works from any branch; see below.) - 4 — **worktree corruption detected.** A parallel session hijacked this worktree (branch swapped, HEAD reset off its stamped baseline, or `start.source-branch` config wiped) while the immune identity sidecar still proves it's a `/start wt` worktree — the PL-454/PL-460 failure mode. The script emits `CORRUPTION=1`, `CORRUPTION_REASON`, `IDENTITY_SOURCE`, and `EXPECTED_BRANCH` / `EXPECTED_BASELINE` / `EXPECTED_SOURCE_BRANCH` alongside the usual context. **Do NOT run the normal flow** — merging would ship a hijacked tree. Jump straight to **Step 0.5**, carrying those `EXPECTED_*` values forward. When `SOURCE_BRANCH` is set (we're in a worktree), the script defaults `ACTION` to `merge`; `/finish pr` is the way to opt into the PR flow with `base = SOURCE_BRANCH`. Outside a worktree, `pr` is allowed (it emits `ACTION=pr` with an empty `SOURCE_BRANCH`, and Step 9 targets the repo's default branch), while `merge` is rejected (exit 2). If both `SOURCE_BRANCH` and `ACTION` are empty, this is the standard `/finish` flow. ### Step 0.5: Worktree Corruption Recovery (only when `finish-detect-mode.sh` exits 4) A parallel `/start wt` session reset this worktree out from under us — exactly what happened to PL-454 and PL-460 when ~8 `/full wt` ran in parallel. The session's intended work is typically uncommitted edits that survived the reset, recoverable by `finish-recover.sh`: it salvages that work to a patch, re-forks a fresh branch off the **current** source tip, re-applies, gates on `pnpm check`, commits, and merges. **Posture: detect-and-stop with ONE confirmation.** Recovery infers which-files-are-mine heuristically when the branch was reset, so never run it unattended. 1. **Surface the corruption** from Step 0's output: `CORRUPTION_REASON`, `IDENTITY_SOURCE`, `EXPECTED_BRANCH` vs the current `WORKTREE_BRANCH`, `EXPECTED_BASELINE`, `EXPECTED_SOURCE_BRANCH`. State plainly what recovery will do (salvage → fresh `.claude/worktrees/-recovered` off `EXPECTED_SOURCE_BRANCH` → re-apply → `pnpm check` → commit → merge → retire the corrupted worktree). 2. **Ask the user (single message, then wait):** > Worktree for `` was hijacked by a parallel session (``). Recover automatically? Reply `yes` to run `finish-recover.sh`, or `abort` to stop and inspect manually. On `abort`: stop with `BLOCKED-ON-RECOVERY: — worktree hijacked (); recovery declined. Corrupted worktree preserved at .` No state change. Do not run any further step. 3. **On `yes`:** Write the work-commit message (must contain the issue ID, e.g. `PL-13:

`) to `/tmp/finish-commit-.md` using the **Write** tool (absolute path). Then run from the MAIN checkout: ```bash cd '' ~/.claude/scripts/finish-recover.sh '' '' '' '' '/tmp/finish-commit-.md' ``` Route on `finish-recover.sh`'s exit code (it prints `RECOVER_DIFF_STRATEGY=` on stderr — quote it in the closing line): - **0** — recovered + merged. The merge owns the Ready-For-Release transition (as in Step 9 exit-0): run `~/.claude/scripts/mark-ready-for-release.sh `, then emit `SHIPPED-MERGE: — worktree was hijacked; work salvaged (), re-forked off , merged, Ready For Release.` Terminal. - **2** — conflict applying/merging in `.claude/worktrees/-recovered`. Resolve there (read the conflicted files listed on stderr, fix, `git -C '.claude/worktrees/-recovered' add `, `pnpm check`), then **re-run the same `finish-recover.sh` line** (it resumes the recovered worktree). If genuinely unresolvable, emit `BLOCKED-ON-RECOVERY: — recovery conflict in .claude/worktrees/-recovered; resolve and re-run finish-recover.sh.` - **3** — merge deferred to the queue (transient). Emit `DEFERRED-MERGE: — recovered work queued (); will retry automatically. Check with /merge-queue.` (The drainer marks Ready For Release when it lands.) - **4** — `pnpm check` failed in the recovered worktree. Emit `BLOCKED-ON-RECOVERY: — pnpm check failed in the recovered worktree; fix in .claude/worktrees/-recovered and re-run finish-recover.sh.` - **1** — setup failure (source branch gone, nothing salvageable). Surface the script's stderr and emit `BLOCKED-ON-RECOVERY: — recovery setup failed: . Inspect manually.` Step 0.5 is terminal for the corruption case — do NOT continue to Steps 1–9. (The work being recovered is the same code `/quality-review` already passed in `/start`, so no separate verdict gate runs here; the user's `yes` is the gate.) ### Step 1: Identify the Issue ```bash ~/.claude/scripts/detect-issue-id.sh [--input ] ``` The script tries `--input` → current branch → latest commit subject, in that order. Pass `--input` only when the user typed an explicit ID (e.g., `/finish PL-12`). On exit 1, ask the user for the identifier explicitly. **Cross-worktree sanity check (standard-flow only).** After the issue ID is resolved, if the standard flow was detected in Step 0 (`ACTION` empty — no worktree config and no explicit `pr`) but the issue's branch exists in a known linked worktree of this repo (`git worktree list` shows a path whose basename or branch contains ``, e.g., `pl-13`), warn the user before continuing: > Issue `` appears to live in worktree ``. Are you running `/finish` from the wrong cwd? Reply `yes` to proceed here anyway, or `abort` and `cd` into the worktree first. Continue only on explicit `yes`. This catches the case where `/start wt` created a worktree, the user opened a fresh terminal in the main checkout, and ran `/finish PL-13` from there — which would otherwise push/commit on the wrong branch. Skip the check entirely when Step 0 detected a worktree (in which case `SOURCE_BRANCH` is set and we're already in the right place), when `ACTION` is `pr` (an explicit `/finish pr` is a deliberate choice to open a PR for the current branch — never a wrong-cwd accident), or when no issue ID was resolved (nothing to check against). ### Step 1.5: Read Quality-Review Verdict + Sub-issues ```bash ~/.claude/scripts/finish-read-verdict.sh PL-12 ``` Emits seven `KEY=value` lines: `VERDICT_FILE`, `VERDICT`, `CYCLES`, `SUB_ISSUES`, `SUB_ISSUES_ERROR`, `VERDICT_STALE`, `VERDICT_STALE_REASON`. **Read those values and carry them forward** — Step 4 embeds them in the completion comment, Step 8 gates the `Ready For Release` transition on `VERDICT` and `VERDICT_STALE`. `VERDICT` is one of: - `passed-clean` / `passed-after-fixes` — `/quality-review` converged cleanly. Step 8 proceeds without prompting. - `terminated-with-open-items` / `escalated-to-architect` — non-passing. Step 8 hard-refuses by default (override prompt; see Step 8). - `malformed` — verdict file exists but cannot be parsed (no `Verdict:` line, the line contains the pipe-separated schema example, or the value is not one of the four recognized enums). Step 8 hard-refuses; the user clearly ran `/quality-review` but the handoff is broken, so silently passing the gate would defeat the safety check. - `none-found` — no verdict file exists at either the current worktree's `tmp/` or the main checkout's `tmp/`. `/quality-review` was either never run for this issue or was run from a different repo. Step 8 warns and proceeds. `SUB_ISSUES` is the parent issue's **current `children` array from Linear** — i.e., every sub-issue that exists under this parent right now, not necessarily ones filed by this `/quality-review` run. Step 4 surfaces this list as context (labeled accordingly), not as a "filed this run" claim. `SUB_ISSUES_ERROR` is populated only if `linear-cli issues get` failed (CLI unauthenticated, missing issue, network blip). Step 1.5 does NOT abort on this — `linear-cli auth oauth` is offered in Step 2's error handling if needed, and the rest of `/finish` can proceed without sub-issue context. Surface the warning text in chat once when populated. `VERDICT_STALE=1` means the verdict file's mtime predates HEAD's commit time — additional commits landed AFTER `/quality-review` ran, so the verdict does not reflect current code. Step 8 escalates passing-but-stale to refuse-with-override (same shape as `malformed`), preventing the gate from sailing through on an out-of-date verdict. The `VERDICT_STALE_REASON` field carries diagnostic text for the override prompt. ### Step 2: Get Issue Details ```bash linear-cli issues get PL-12 ``` Read the description carefully. Note: - Requirement checkboxes (`- [ ]` items) - Success criteria checkboxes - Any "Nice to Have" vs "Must Have" distinctions ### Step 3: Read Current Description as JSON ```bash linear-cli issues get PL-12 --output json ``` Identify each `- [ ]` checkbox and decide which were completed this session. Don't post anything yet — Step 5 sends the updated description and the completion comment together. ### Step 4: Generate Completion Comment Write a markdown comment summarizing the work. **Every `<...>` token below is a substitution site — replace each one with the resolved value before posting; never emit a literal `` to Linear.** Template: ```markdown ## Implementation Complete Branch: `` ### What was done - Bullet points of key changes (files created/modified, features implemented) ### Design decisions - Key technical choices and why they were made ### Verification - What was verified (type checks, tests, dev server, etc.) ### Adversarial review - Verdict: (cycles: ) - Sub-issues (current children of this issue): - Open items: ### Notes - Any unchecked items with explanation of why - Any follow-up work identified ``` Omit sections that have no content (e.g., skip "Notes" if everything was completed). Omit the **Adversarial review** section entirely when `VERDICT=none-found` (no `/quality-review` ran). When the verdict is passing, drop the `Open items` bullet but keep the other two. ### Step 5: Post Description Update + Completion Comment Write both files: 1. `tmp/linear-description-.md` (e.g., `tmp/linear-description-pl-12.md`) — full description with `- [ ]` flipped to `- [x]` for completed items. Preserve everything else exactly. 2. `tmp/linear-comment-.md` (e.g., `tmp/linear-comment-pl-12.md`) — completion-comment body from Step 4. Then post both in one call: ```bash ~/.claude/scripts/finish-post-update.sh PL-12 tmp/linear-description-pl-12.md tmp/linear-comment-pl-12.md ``` Exit codes: 1 (validation — missing/empty files), 2 (Linear API failure). ### Step 6: Verify Check Passes Run `pnpm check` as a hard gate before committing: ```bash pnpm check ``` If it **fails**: this is CRITICAL. Do not commit or push. Fix the failures first, then re-run until it passes. If it **passes**: proceed to commit. ### Step 7: Git Commit & Push 1. Stage relevant files by name (`git add `). Never `git add -A` / `git add .` (per CLAUDE.md). 2. Write the commit message to `tmp/finish-commit-.md` (e.g., `tmp/finish-commit-pl-13.md`). The issue ID **must** appear in the message (the script enforces it for Linear auto-linking): ```text PL-13: ``` 3. Run the commit script: ```bash ~/.claude/scripts/finish-commit.sh PL-13 tmp/finish-commit-pl-13.md [--no-push] ``` **`--no-push` is required in TWO cases — easy to miss the second:** 1. The user requested `no push` / `don't push` / `skip push` (Step 0 translates these to `NO_PUSH=1`). 2. **`ACTION=merge`** — the temp branch is about to be merged into source and deleted locally; pushing it pollutes origin with abandoned branches. The merge commit reaches origin later via the source branch. If either condition holds, pass `--no-push`. The script does NOT enforce this rule (it has no awareness of `ACTION`), so the orchestrator MUST gate on `NO_PUSH=1 OR ACTION=merge`. The script handles all three states: pre-staged changes (commit + push), already-committed-but-ahead (push only), already-synced (no-op). If staging is missing for an unstaged-only state, it errors with exit 2 — go back and `git add` the files. ### Step 8: Mark Issue as Ready For Release **Skip when `ACTION == "pr"`.** In PR mode, the work is not yet shipped — review and merge are still pending. Leave the issue in `In Progress`; the transition to `Ready For Release` happens after the PR merges (manually, or via a follow-up `/finish` once the worktree branch is merged into source). In all other cases (no worktree, or `ACTION == "merge"`), gate the transition on the `VERDICT` from Step 1.5. **Every `<...>` token in the prompt and comment bodies below is a substitution site** — replace each with the resolved value before emitting; never write a literal `` to chat or to Linear. The Step 4 substitution rule applies here too. **Who performs the `Ready For Release` transition (read before any branch below).** The transition belongs to whoever *completes the lifecycle*, so Linear never shows `Ready For Release` for code that is not yet merged: - **Standard flow (`ACTION` empty):** Step 8 runs `linear-cli issues update --state "Ready For Release"` inline (the commands in the branches below) — there is no merge to wait for. - **`ACTION == "merge"`:** Step 8 runs the verdict **gate only** (the proceed / abort / override decisions below) and does **NOT** run `linear-cli issues update`. The merge owns the transition: Step 9 runs it via `~/.claude/scripts/mark-ready-for-release.sh ` **only after `finish-merge.sh` exits 0** (the merge actually landed), and the launchd drainer runs the same script when it lands an async deferral. So wherever a branch below says "proceed with the state update", in `merge` mode that means **proceed to Step 9 without changing Linear state** — the gate passed; the merge (now, or later via the queue) transitions it. On a deferred merge (exit 3) the issue therefore stays **In Progress**, which is the truth: it is not released until it is merged. **Override-comment wording in merge mode:** the override comments in the branches below — posted when the user accepts a stale/failing verdict — still post here at gate time, but in `merge` mode they must record *authorization*, not a completed transition. Replace the literal `marked Ready For Release` in any such comment body with `authorized Ready For Release (the merge applies it when it lands)` — otherwise the comment re-tells the very lie this ordering exists to prevent (asserting a release state while the code is unmerged and the issue is still In Progress). The standard flow (`ACTION` empty) keeps `marked Ready For Release` — there the state really is changed here. - **`ACTION == "pr"`:** Step 8 is skipped entirely (handled above). **Step 8 termination contract — applies to ALL branches below.** Per `standards/lifecycle-tags.md`, every terminal path of `/finish` Step 8 ends with exactly one tagged final line. (The Preflight has its own independent terminator — `BLOCKED-ON-REVIEW` on plan-mode rejection or `ExitPlanMode` tool failure — and never reaches Step 8.) Mechanical mapping (do not skip): - A branch that completed `linear-cli issues update --state "Ready For Release"` AND `ACTION` from Step 0 is empty (standard flow, no Step 9 to follow) → emit `RELEASED: — ` as the last LLM-authored line. - A branch that passed the verdict gate AND `ACTION == "merge"` → do NOT change Linear state and do NOT emit a tag here (per "Who performs the transition" above, merge mode defers the state update). Step 9 owns BOTH the Ready-For-Release transition (after the merge lands) and the terminal line (`SHIPPED-MERGE:` on a completed merge, or `DEFERRED-MERGE:` when `finish-merge.sh` exits 3 and the merge is queued — the issue stays In Progress until it lands). (`ACTION == "pr"` never reaches a state update — Step 8 is skipped for it — so it isn't in these bullets; Step 9 owns `SHIPPED-PR:`. Discriminate on `ACTION`, not `SOURCE_BRANCH`: a non-worktree `pr` has an empty `SOURCE_BRANCH` yet still flows to Step 9.) - A branch that exited via the user picking `abort` or `re-run` at the gate prompt → emit `BLOCKED-ON-REVIEW: — ` as the last LLM-authored line. State was NOT changed. - A branch that warned-and-proceeded (`none-found`) → same as the first/second bullets depending on `ACTION`, **unless `linear-cli issues update` itself fails, in which case bullet 5 supersedes**. - **A branch where `linear-cli issues update` itself failed** (API error, auth dropped mid-session, team's terminal state name differs from `Ready For Release`) → see the **State-update failure** section below for the recovery + terminator rule. **This bullet supersedes bullets 1, 2, and 4 whenever the state update doesn't succeed** — never emit `RELEASED:` on a failed update. The per-branch instructions below indicate which terminator each branch uses; trust the contract above for the literal tag wording. **State-update failure recovery (applies to every branch that attempts `linear-cli issues update --state "Ready For Release"`).** If the call exits non-zero: 1. Inspect the error. If it's a "no such state" rejection (the team uses a different terminal state name), apply this probe-and-match fallback — analogous to `/start` Step 8.5's CANCELED/ABANDONED fallback and `/quality-review` sub-step 6's fallback: - Derive the team key from the issue ID prefix (e.g., `PL-13` → team `PL`). Then probe: `linear-cli statuses list -t PL`. - Pick the first state whose name matches `/^ready[ _-]?for[ _-]?(release|deploy|ship)$/i` (exact match — NOT a prefix match — to avoid latching onto `Ready For Review`; the `[ _-]?` separator class matches `Ready For Release`, `Ready_For_Release`, `Ready-For-Release`, `ReadyForRelease`). - If found, retry `linear-cli issues update --state ""`. If it succeeds, emit the standard-flow terminator `RELEASED:`. **This whole recovery applies only to the standard flow** (`ACTION` empty) — per "Who performs the transition" above, `ACTION == "merge"` does not run `linear-cli issues update` in Step 8 at all, so there is no Step-8 update to recover here; the merge owns the transition (Step 9 / the drainer via `mark-ready-for-release.sh`, which carries this same fallback). - If no match, OR if the retry also fails, fall through to step 2. - **Note on bare `Ready`:** the regex deliberately requires `Ready For ` and does NOT match a bare `Ready` state. A team's `Ready` state is too ambiguous (could mean ready-for-review, ready-for-QA, etc.) to auto-route into — the issue falls through to step 2's BLOCKED-ON-REVIEW. To use bare `Ready` as a release state, rename it to `Ready For Release` or add canonical config. 2. Surface the error to the user and emit `BLOCKED-ON-REVIEW: — linear-cli issues update failed: . State NOT changed; this issue remains In Progress.` as the terminator. **Distill `` to a single line**: if the CLI returned a multi-line error (stack trace, JSON error body), take the first informative line (typically the error message) and drop the rest — the tag must fit on one line so the agents-list parser picks it up correctly. Do NOT silently emit `RELEASED:` (it would lie about the state) and do NOT continue to Step 9 (worktree flow can't ship an issue whose state didn't transition). - **`passed-clean` / `passed-after-fixes`** — proceed, BUT first check `VERDICT_STALE`: - `VERDICT_STALE=0` → proceed with the state update: ```bash linear-cli issues update PL-12 --state "Ready For Release" ``` **Terminator:** `RELEASED:` (non-worktree) or none (worktree; Step 9 emits). - `VERDICT_STALE=1` → **refuse with override.** The verdict says "passing" but was produced before the latest commits — it may not reflect current code. Prompt the user: > Quality-review verdict is `` but is **stale**: ``. Additional commits landed after `/quality-review` ran, so the verdict may not reflect current code. > > Mark `Ready For Release` anyway? Reply `yes` to override (the prior verdict was passing and you've verified the new commits don't introduce findings), `re-run` to invoke `/quality-review` and produce a fresh verdict for current HEAD, or `abort` to stop here. On `yes`: proceed with the state update AND post an override comment: `Override: marked Ready For Release on stale verdict (additional commits since /quality-review ran). User-acknowledged.` **Terminator:** `RELEASED:` (non-worktree) or none (worktree). On `re-run`: stop with `Re-run /quality-review to produce a fresh verdict for current HEAD, then retry /finish.` **Terminator:** `BLOCKED-ON-REVIEW: — stale verdict, user opted to re-run /quality-review against current HEAD before /finish.` On `abort`: stop with no state change. **Terminator:** `BLOCKED-ON-REVIEW: — stale verdict, user aborted at /finish gate. No state change.` - **`terminated-with-open-items` / `escalated-to-architect`** — **refuse by default.** The implementation has known unresolved findings per `/quality-review`. Before composing the prompt, `Read` the file at `VERDICT_FILE` and extract the `Open items:` line (and any continuation lines, if `Open items:` is followed by an indented bullet list). Substitute that text into the prompt below — never emit the literal placeholder ``. **If `VERDICT_STALE=1`, prepend a staleness note to the prompt** so the user knows the open-items list may not reflect current code (recent commits may have resolved some). Then prompt the user (single message, wait for reply): > Quality-review verdict is `` with open items: > > `` > > [If `VERDICT_STALE=1`, include: `Note: the verdict is stale — . The open items above may have already been resolved by the more recent commits.`] > > Mark `Ready For Release` anyway? Reply `yes` to override, `re-run` to invoke `/quality-review` and try to converge, or `abort` to stop here. On `yes`: proceed with the state update AND post an additional Linear comment recording the override — body: `Override: marked Ready For Release despite verdict . Open items at override time: . User-acknowledged.` (If `VERDICT_STALE=1`, append: ` Verdict was stale; user explicitly accepted the risk of overriding without a fresh /quality-review.`) Use `~/.claude/scripts/linear-post.sh` to post. **Terminator:** `RELEASED:` (non-worktree) or none (worktree). On `re-run`: stop `/finish` with the message `Re-run /quality-review to address open items, then retry /finish.` Do not change state. **Terminator:** `BLOCKED-ON-REVIEW: — verdict , user opted to re-run /quality-review before /finish.` On `abort`: stop with no state change and no further output. **Terminator:** `BLOCKED-ON-REVIEW: — verdict , user aborted at /finish gate. No state change.` - **`malformed`** — verdict file exists at `VERDICT_FILE` but cannot be parsed (no `Verdict:` line, or value is the pipe-separated schema example, or value is not one of the four recognized enums). **Refuse with the same prompt as the non-passing path above**, but with this preamble instead of the open-items list: > Quality-review verdict file exists at `` but is malformed (no recognized verdict value). The user clearly ran /quality-review, but the handoff is broken — silently marking Ready For Release would defeat the safety check. > > Mark `Ready For Release` anyway? Reply `yes` to override (consider inspecting the file first), `re-run` to invoke `/quality-review` and produce a fresh artifact, or `abort` to stop here. Same response handling as the non-passing path: `yes` posts an override comment (body: `Override: marked Ready For Release despite malformed /quality-review verdict file. User-acknowledged.` — do NOT include `VERDICT_FILE`'s absolute path in the comment body, since Linear comments are not necessarily private and the path leaks the user's home directory and project layout); `re-run` stops with the re-run suggestion; `abort` stops. **Terminators:** `yes` → `RELEASED:` (non-worktree) or none (worktree); `re-run` → `BLOCKED-ON-REVIEW: — malformed verdict, user opted to re-run /quality-review.`; `abort` → `BLOCKED-ON-REVIEW: — malformed verdict, user aborted at /finish gate. No state change.` - **`none-found`** — no verdict file located. Warn once: `No /quality-review artifact found for this issue. Proceeding without gate. Consider running /quality-review before /finish next time.` Then proceed with the state update. **Terminator:** `RELEASED:` (non-worktree) or none (worktree). (Backward compatibility for issues finished before this gate existed.) - **Any other value** (defense in depth — shouldn't happen since the script normalizes everything else to `malformed`) → treat as `malformed`. Do NOT proceed silently. **Terminators:** same as `malformed`. ### Step 9: Finalization (only when `ACTION` is `merge` or `pr`) Runs only when `ACTION` is `merge` or `pr`. Skip entirely when `ACTION` is empty (the standard flow ended at Step 8). `merge` always implies a worktree (`SOURCE_BRANCH` set); `pr` runs with or without one. **Step 9 is the terminal step of this session** — for all modes. After the merge (or `gh pr create`) completes, present the closing message and stop. Don't run further bash commands. Substitute the values captured from Step 0 (`SOURCE_BRANCH`, `WORKTREE_BRANCH`, `WT_DIR`, `REPO_ROOT`) into the bash commands below as literal strings. **If `ACTION == "merge"`:** The script brings the worktree branch up to source's tip **inside the worktree** (where this session can edit even under bgIsolation, and where no lock is needed because the worktree is private to this session), then **advances source to it** — by `git merge --ff-only` when the main checkout is on source, or by an atomic ref update (`git update-ref`, compare-and-swap) when it's on another branch. Either way the advance never merges in the main checkout, never leaves it mid-merge, and never switches its HEAD. The common case — worktree branch one commit ahead, source unmoved — collapses to a single `PL-XXX:

` line in `git log` with no merge commit. Only when source moved during the worktree's life is a merge commit created (with the prepared one-line `Merge PL-XXX` subject, avoiding the verbose default boilerplate); any conflicts from that are resolved **in the worktree**, never the main checkout. This is what makes the merge safe to run concurrently and from a background session. 1. **Write the merge-commit message** to `/tmp/git-merge-msg-.md` (e.g., `/tmp/git-merge-msg-pl-13.md`; substitute the actual `WT_DIR` value from Step 0). Use the `Write` tool — it requires an absolute path. A single line is all that's needed; it's only used in the rare divergent-merge case (or during conflict resolution), and the issue ID is what Linear auto-links on: ```text Merge PL-13 ``` 2. **Run the merge in a single Bash tool call** — `cd` to the main checkout (the script removes the worktree on success, so cwd must not be inside it), then call `finish-merge.sh`: ```bash cd '' ~/.claude/scripts/finish-merge.sh '' '' '' '/tmp/git-merge-msg-pl-13.md' ``` The script self-serializes against other `/finish merge` sessions targeting the same parent repo. If another session holds the merge slot, the Bash call will print `[finish-queue] waiting for ...` on stderr and block until its turn — surface that output to the user as-is and wait. The lock is released by the OS when the script exits (success, error, or crash); no manual cleanup is needed. **Exit codes:** - **0 (success)** — the merge landed, so **now** perform the Ready-For-Release transition that Step 8 deferred (the merge owns it): 1. Run `~/.claude/scripts/mark-ready-for-release.sh ` — moves the issue to Ready For Release with the same team-state fallback Step 8 documents. - **Exit 0** → proceed to the closing message below. - **Non-zero** → the merge succeeded but the Linear update failed. Do **NOT** undo the merge. Surface the script's error and emit, as the terminal line, `SHIPPED-MERGE: — merged into , worktree removed, but Linear state update FAILED: . Mark Ready For Release manually.` (still `SHIPPED-MERGE` — the code shipped; only the bookkeeping needs a manual touch). Then stop. 2. On success, surface the merge output and present the closing message. The tagged final line (per `standards/lifecycle-tags.md`) MUST be the last LLM-authored output: ```text This agent-view session is done — close it and dispatch a new session for the next issue. SHIPPED-MERGE: — merged into , worktree removed, Ready For Release. ``` Do not run further bash commands. - **1 (hard precondition failure)** — surface the script's output and stop. Don't attempt recovery; these are genuine setup problems the user must resolve (source branch missing, worktree gone or on the wrong branch, worktree mid-unrelated-operation or with uncommitted tracked changes, or the merge couldn't be verified). The terminal tagged line is `BLOCKED-ON-REVIEW: — . .` Do not run further bash commands. (Transient blocks — dirty/on-source main checkout, source checked out elsewhere, main mid-operation, contention — are **exit 3**, not 1; see below.) - **3 (transient block — deferred to the merge queue)** — the merge can't advance the source branch *right now* but will succeed later untouched (the main checkout is on the source branch with uncommitted WIP, the source branch is checked out in another worktree, the main checkout is mid-operation, or the source branch is under continuous contention). The script has **already self-enqueued** the merge to the local queue (`scripts/merge-queue.sh`); a launchd drainer retries until it lands, and **the drainer marks the issue Ready For Release when it does**. The worktree is intact and the issue **remains In Progress** — Step 8 deliberately did NOT mark it Ready For Release (the merge owns that transition, and the merge hasn't landed). That is the honest state: it is not released until it is merged. So there is **nothing more to do** here — do **not** retry, commit, mark the issue Ready For Release, or touch any other session's changes. Surface the script's `DEFERRED:` output and present the terminal tagged line (substitute the script's reason): ```text Merge deferred — it'll retry automatically once the blocker clears. Inspect any time with /merge-queue. DEFERRED-MERGE: — merge queued (); will retry automatically. Check with /merge-queue. ``` Do not run further bash commands. - **2 (merge conflict — resolve in the worktree)** — the script merged `` into the worktree branch **inside ``** and hit conflicts. The main checkout is untouched and clean; the conflict lives in the worktree, which this session **owns** (edits there are permitted even under bgIsolation) and which is **private** (no lock needed — do **not** wrap these in `with-repo-lock.py`). Conflicted files are listed on the script's stderr as worktree-relative paths. 1. For each conflicted file: read it from `/`, understand both sides of the conflict, apply the resolution. When one side clearly subsumes the other (e.g., the worktree branch removed code the source side modified), take the subsuming side. Ask the user only when the right answer is genuinely ambiguous. 2. `git -C '' add ` 3. Run `pnpm check` from `` — must be green before committing. If it fails: the conflict resolution introduced a regression. Per the Working Application Contract, do **not** commit and do **not** re-invoke. Surface the failing output to the user; let them decide between fixing the resolution further, aborting the merge (`git -C '' merge --abort`), or escalating to architect. The mid-merge state is preserved in the worktree for inspection. 4. `git -C '' commit -F '/tmp/git-merge-msg-.md'` — reuse the prepared merge-commit message (e.g., `/tmp/git-merge-msg-pl-13.md`). 5. **Re-invoke the same Step 2 `finish-merge.sh` line.** It re-acquires the lock and fast-forwards the main checkout, then removes the worktree and branch. If source advanced during your resolution, it re-merges the new delta — which may return **2 again** with a fresh conflict on that delta; if so, **repeat steps 1–5**. This is expected under concurrent `/finish merge` sessions and converges (each round reconciles only the latest source delta). 6. Present the closing message above once the re-invocation exits 0. **If `ACTION == "pr"`:** The branch was pushed in Step 7 (the `no push` + `pr` combination was rejected in Step 0). Open a PR for the current branch — this works whether or not we're in a worktree. 1. **Resolve the base branch:** - `SOURCE_BRANCH` is set (we're in a `/start wt` worktree) → base = `SOURCE_BRANCH`. - `SOURCE_BRANCH` is empty (plain-branch PR) → base = the repo's GitHub default branch: ```bash gh repo view --json defaultBranchRef -q .defaultBranchRef.name ``` If this fails (no GitHub remote, `gh` unauthenticated), surface the error and stop — there's nowhere to open the PR. Don't guess a base. The base is the default branch by design even when the branch was forked off another branch; the user can retarget the PR in GitHub if it should land elsewhere. 2. **Verify any requested labels exist** (only if Step 0 collected labels). Check each label with an exact-equality `jq` filter (a substring like `deploy` must NOT match an existing `pr-deploy`) — the command prints the label name if it exists and nothing if it doesn't: ```bash gh label list --limit 200 --json name -q '.[].name | select(. == "")' ``` If a requested label is missing (empty output), do NOT silently drop it. Surface it and ask the user: proceed without that label / create it (`gh label create ''`) / abort. Apply only labels that exist (or that the user just created). 3. **Generate the PR title and body from the actual diff** — do NOT use `--fill` (it only echoes the commit message). Apply the `pr-update` skill's methodology directly: read [`~/.claude/skills/pr-update/SKILL.md`](../pr-update/SKILL.md) and follow its Analysis Process (§2–6), PR Title Formats, and Description Structure. **Skip pr-update's own base-resolution** (its §2 `if [[ -n "$pr_info" ]]; … BASE=…` prologue) and substitute the `` you already resolved in sub-step 1 wherever its commands reference `$BASE` — in a worktree that base is `SOURCE_BRANCH`, **not** the default branch, and letting pr-update re-resolve `$BASE` would diff the worktree PR against the wrong base. This is a **by-reference** use of that methodology — read its sections and apply them here — **not** a `Skill`-tool dispatch of `pr-update`: `/finish` must stay the authority over the base, labels, and the terminal `SHIPPED-PR` tag, and must not trigger `pr-update`'s own interactive PR-state prompts. The branch is already pushed (Step 7), so no push here. (pr-update's own empty-`$BASE` guard lives in the §2 prologue you're skipping; sub-step 1 above is the backstop for this path — it already stops if it cannot resolve a base, so the substituted `` is non-empty by the time you reach here.) 4. **Write the body** to `/tmp/pr-body-.md` (worktree mode) or `/tmp/pr-body-.md` (in-place) using the **Write** tool (it requires an absolute path) — the same pattern as the merge-commit message file in the `merge` branch above. 5. **Create the PR** — pass `--base` explicitly, the generated title, the body file, and one `--label` per verified label: ```bash gh pr create --base '' --head '' --title '' --body-file '' [--label '' ...] ``` After the PR is created, present the closing message. The tagged final line (per `standards/lifecycle-tags.md`) MUST be the last LLM-authored output. Substitute the actual resolved ``, branch, and label list (or the bare word `none` when no labels were applied). The message branches on whether a worktree is involved: - **`SOURCE_BRANCH` set (worktree PR)** — leave the worktree in place; it's the lifecycle boundary. The leading sentence and the tagged line should NOT duplicate the cleanup hint: ```text This agent-view session is done. The worktree stays in place until the PR merges. SHIPPED-PR: — PR opened (base=, head=), labels: . After merge, run `git worktree remove .claude/worktrees/` from the main checkout. ``` After the PR merges, the user removes the worktree manually from the main repo checkout: ```bash # cd to the main repo checkout (parent of .claude/worktrees/), then: git worktree remove .claude/worktrees/ ``` - **`SOURCE_BRANCH` empty (plain-branch PR)** — there is no worktree to clean up; omit the worktree hint entirely: ```text This agent-view session is done. The PR is open against — review and merge it there. SHIPPED-PR: — PR opened (base=, head=), labels: . Review/merge the PR. ``` ## Error Handling - If the issue is already Ready For Release or Done, warn the user and ask if they want to proceed (add comment only) - If there are no uncommitted changes and code is already pushed, skip the git steps - If `linear-cli` is not authenticated, prompt: `linear-cli auth oauth` - If the issue identifier can't be found, ask the user explicitly

finish

Install this skill

Comments