Finish (`/flow:finish`)

Finish (/flow:finish)

Overview

Ship work only after fresh verification. Present options. Execute the chosen one. Never act without an explicit choice.

Core principle: Verify first, present exactly 4 options, wait for a decision, then execute.

This skill is invoked:

• After /flow:verify reports all criteria PASS
• Manually when the user runs /flow:finish

Never auto-merge or auto-push. The skill presents options and waits. The user decides.

---

Step 1: Re-Run Tests (Fresh Evidence)

Do not rely on the verify step's results. Re-run now, in this message.

Detect the project language first:

[ -f tsconfig.json ] && echo "TypeScript"
[ -f Cargo.toml ] && echo "Rust"
{ [ -f pyproject.toml ] || [ -f setup.py ]; } && echo "Python"

Then run the appropriate test command:

TypeScript:

npx tsc --noEmit && bun test

Python:

ruff check . && mypy . && pytest

Rust:

cargo check && cargo test

If tests fail — STOP.

Report the failures with their full output:

Tests failing (N failures). Cannot proceed to ship.

[show exact failure output]

Fix the failures and re-run `/flow:finish`.

Do not proceed to Step 2. Return control to the user.

If tests pass: Continue.

---

Step 2: Determine Base Branch

git branch --show-current
git branch --list main master

If main exists, use main as the base branch. If only master exists, use master. If neither main nor master is found, ask the user: "What is the base branch?"

---

Step 3: Present Exactly 4 Options

Present these options verbatim, substituting <base-branch> with the detected branch name:

Tests pass. What would you like to do with this branch?

1. Merge back to <base-branch> locally
2. Push and create a Pull Request
3. Keep the branch as-is
4. Discard this work

Which option? (1/2/3/4)

Do not add explanations, recommendations, or commentary. Do not suggest an option. Wait for the user's answer.

---

Step 4: Execute the Chosen Option

Option 1: Merge Locally

# Get the current feature branch name
FEATURE_BRANCH=$(git branch --show-current)

# Switch to base branch
git checkout <base-branch>

# Pull latest
git pull

# Merge feature branch
git merge "$FEATURE_BRANCH"

After merging, re-run tests on the merged result:

# Run the same test command from Step 1

If the post-merge tests fail: do not delete the feature branch. Report the failures and stop.

If the post-merge tests pass:

git branch -d "$FEATURE_BRANCH"

Report: "Merged <feature-branch> into <base-branch>. Branch deleted."

---

Option 2: Push and Create a Pull Request

# Push the feature branch
git push -u origin $(git branch --show-current)

Then create the PR using gh pr create. Pull the summary from the plan file:

# Find the plan
ls docs/plans/ | sort | tail -1

Read the plan's Goal line and task list. Use them in the PR body:

gh pr create --title "<feature name from plan Goal>" --body "$(cat <<'EOF'
## Summary

<2-3 bullet points from the plan's task list — what was built, not how>

## Test results

- Type check: PASS (npx tsc --noEmit)
- Tests: PASS (N/N passing)
- Acceptance criteria: N/N PASS

## Plan

docs/plans/<plan-filename>
EOF
)"

Report the PR URL when gh pr create returns it.

---

Option 3: Keep the Branch As-Is

Report: "Keeping branch <feature-branch>. No changes made."

Do not delete anything. Do not merge anything. Done.

---

Option 4: Discard This Work

First, show exactly what will be deleted:

git log <base-branch>..HEAD --oneline

Display:

This will permanently delete:

Branch: <feature-branch>
Commits to be lost:
  <commit hash> <commit message>
  <commit hash> <commit message>
  ...

Type "discard" to confirm. This cannot be undone.

Wait for the user to type exactly discard. Accept nothing else — not "yes", not "ok", not "confirm".

If the user does not type discard: abort. Report: "Discard cancelled. Branch preserved."

If the user types discard:

FEATURE_BRANCH=$(git branch --show-current)
git checkout <base-branch>
git branch -D "$FEATURE_BRANCH"

Report: "Branch <feature-branch> and all its commits have been deleted."

---

Step 5: Worktree Cleanup

Check if a worktree was used for this branch. Use the FEATURE_BRANCH variable captured at the top of the chosen option block — do NOT use git branch --show-current here, because Options 1 and 4 have already checked out the base branch by this point.

git worktree list | grep "$FEATURE_BRANCH" 2>/dev/null

• Option 1 (merge) and Option 4 (discard): Remove the worktree if present:

  git worktree remove <worktree-path>
  

• Option 2 (PR) and Option 3 (keep): Leave the worktree intact.

---

Quick Reference

Option	What happens	Worktree
1. Merge locally	Merges to base, deletes feature branch	Removed
2. Push + PR	Pushes branch, creates GitHub PR	Preserved
3. Keep as-is	Nothing changes	Preserved
4. Discard	Deletes all commits, deletes branch	Removed

---

Red Flags — Never Do These

• Never merge without running fresh tests in this skill. The verify step's results are stale by definition.
• Never push without an explicit Option 2 choice.
• Never delete a branch without the exact typed word "discard" for Option 4.
• Never force-push unless the user explicitly requests it.
• Never offer a 5th option or improvise on the 4 options presented.
• Never proceed with failing tests. Full stop.

---

Common Mistakes

Skipping the Step 1 re-run because /flow:verify just passed. Verify ran earlier. Code may have changed. Run the tests again now.

Adding a recommendation when presenting options. "I'd suggest option 2" — don't. Present the options. Wait.

Accepting "yes" instead of "discard" for Option 4. The exact word is the guard. If someone types "yes", ask again.

Forgetting to check for worktrees. A dangling worktree is a future confusion. Always check and clean up for Options 1 and 4.