run-finish

Finish

You are reviewing and completing a PR lifecycle. This skill runs from the main session (project root, not a worktree) after an orchestrator has opened a PR.

Prerequisites

Directives: If docs/ritual-config.json exists, read directives.delivery from the config. These are soft guidelines that influence review standards and merge preferences. Apply them during PR review and merge decisions. If the field is missing or empty, proceed without directives.

Step 1: Validate context

Confirm you are in the main repo (not a worktree):

test -f .git && echo "WORKTREE — wrong context" || echo "MAIN REPO — correct"

If in a worktree, tell the user: "This skill must run from the project root (main session), not from inside a worktree."

Step 2: Identify the PR

List open PRs on this repo:

gh pr list --state open --limit 20

• If there is exactly one open PR, use it automatically.
• If there are multiple, present the list and ask the user which PR to review.
• If there are none, tell the user: "No open PRs found. Nothing to finish."

Step 3: Review the PR

Fetch the PR details:

gh pr view <number> --json number,title,headRefName,body,commits,files,additions,deletions
gh pr diff <number>

Evaluate the following:

3a. Conventional Commits compliance

Check every commit message in the PR. Valid types: feat, fix, refactor, docs, test, chore, ci, perf, style, build. Each message must follow <type>: <description> or <type>(<scope>): <description>.

3b. Diff quality

• No debug code (console.log, debugger, print( used for debugging, TODO, FIXME, HACK)
• No commented-out code blocks
• No sensitive data (API keys, tokens, passwords)

3c. Scope alignment

• Read the PR body's Summary section
• Verify the diff only touches what the summary describes — flag scope creep

3d. Test coverage

• If the PR adds or changes behavior, check that corresponding test files are included
• For pure-config repos (no test runner), skip this check

3e. Version staleness

If the PR touches version files (e.g., marketplace.json, plugin.json), compare the base version in the PR diff against the current version on main:

git show main:marketplace.json 2>/dev/null | head -20

If the PR's base version (the - side of the diff) does not match main's current version, the branch needs a rebase before merging. Flag this as "needs rebase" and stop — do not approve or merge.

Step 3f: CodeRabbit review check

Read docs/ritual-config.json and check if integrations.coderabbit is true.

If enabled, check CodeRabbit's review status on this PR:

gh pr reviews <number> --json author,state

Look for a review from CodeRabbit (author containing "coderabbit"). Evaluate the result:

• If CodeRabbit has approved: Proceed normally to Step 4.
• If CodeRabbit has requested changes: Include CodeRabbit's review comments in the review report. Present them to the user alongside your own review findings.
• If CodeRabbit has not reviewed yet: Warn the user: "CodeRabbit review is pending. You may want to wait for it before merging." Proceed to Step 4 — do not block the pipeline.

If integrations.coderabbit is false or the config file does not exist, skip this check.

Step 4: Deliver verdict

If changes are needed:

Present a structured review using the template below. You MUST fill in the Suggested Fix Prompt section with a concrete, actionable prompt. Do not leave it blank, do not use a generic placeholder, and do not simply restate the issue list. The prompt must be a ready-to-paste instruction that tells the developer exactly what to change, in which files, and how.

## PR Review: <PR title>

### Issues Found
1. <issue description>
2. <issue description>

### Suggested Fix Prompt

Copy and paste the following into your orchestrator session (in the worktree):

> <GENERATE A CONCRETE PROMPT HERE — see rules below>

Prompt generation rules (mandatory):

• The prompt MUST be a single, self-contained instruction that can be copy-pasted verbatim into a Claude session.
• It MUST reference the specific file(s) and line(s) or section(s) that need to change.
• It MUST describe the expected change (e.g., "rename X to Y", "remove the debug line at line 42", "add a guard clause for null input in function Z").
• It MUST NOT simply repeat the issues list — it should synthesize the issues into one clear fix instruction.
• Format it as a direct imperative (e.g., "In src/api.ts, fix the error handler on line 35 to return a 401 instead of 500 when the token is expired, and remove the console.log on line 22.").

Then tell the user:

Fix the issues above, then run /run-finish again to re-review.

Stop here. Do not merge or clean up.

If PR looks good:

Tell the user the PR passes review, then proceed to Step 5.

Step 4b: Check Linear issue reference

Read docs/ritual-config.json and check if integrations.linear is true.

If enabled, check the PR body and branch commits for a Linear issue reference. Linear issue IDs typically appear in the PR body under "Linear Issues" or in the handoff frontmatter (linear-issue field). Record the Linear issue ID if found — it will be used in Step 5b.

If integrations.linear is false or the config file does not exist, skip this check.

Step 5: Version bump

After the PR passes review, apply a version bump before merging. This centralizes version bumping that was previously done by each orchestrator.

5a. Determine bump type

Derive the default bump type from the PR branch name prefix:

Branch prefix	Default bump
feat/	MINOR
fix/	PATCH
refactor/	PATCH
docs/	none

To get the branch name:

gh pr view <number> --json headRefName --jq '.headRefName'

Extract the prefix (everything before the first /). If the prefix does not match any row above, default to PATCH.

5b. Check for milestone target version

Check if the PR has a milestone assigned:

gh pr view <number> --json milestone --jq '.milestone.title // empty'

If a milestone is present and its title is a valid semver string (e.g., 0.10.0, 1.0.0):

1. Parse the milestone title as the target version.
2. This target version will override the standard bump logic in Step 5c — instead of incrementing, the version will be set directly to the milestone's target version.
3. Store the target version for use in Step 5c.

If the milestone title is not a valid semver string (e.g., "Q2 Release", "Sprint 5"), treat it as informational only and fall through to the standard bump logic.

If no milestone is assigned, proceed to the standard bump logic.

5b2. Check for explicit override

Read the PR body and commit messages for an explicit version-bump: directive (e.g., version-bump: major). If found, use that instead of the branch-derived default. Note: milestone target version (Step 5b) takes precedence over explicit overrides.

5c. Apply the bump

If the bump type is none and no milestone target version is set, skip this step.

Otherwise, check out the PR branch locally and apply the semver bump:

git fetch origin <branch>
git checkout <branch>

Semver Bump Procedure

1. Read versioning rules

Read the versioning array from docs/ritual-config.json. Each entry is a natural-language rule string that specifies which version manifest to bump and under what conditions.

Example rules:

• "Bump package.json version for all changes"
• "Bump frontend/package.json version for changes under frontend/"
• "Bump api/pyproject.toml version for changes under api/"

If the versioning array is empty or absent, skip the version bump entirely.

2. Evaluate which rules apply

For each versioning rule:

1. Parse the rule to identify the manifest path and the condition (e.g., "changes under frontend/", "all changes", "for API changes").
2. Check the current diff (git diff main...HEAD) against the condition:
   • "all changes" or no condition specified -- always matches
   • "changes under /" -- matches if any files in the diff are under that path
   • Domain-specific conditions (e.g., "for API changes") -- evaluate based on the diff content and handoff scope
3. Collect all matching rules. Multiple rules can match simultaneously (monorepo scenario).

If no rules match the current change, skip the version bump.

3. Determine bump type

Milestone-aware path (highest priority): If a milestone target version was found in Step 5b:

1. Read the current version from the first matching manifest file.
2. Compare the current version against the milestone target version using semver comparison.
3. If current version < target version: Skip the standard bump logic entirely. The target version from the milestone will be used as the new version in Step 4. This ensures all features within the same milestone converge to the same target version.
4. If current version >= target version: The milestone target has already been reached (by a previously merged PR in the same milestone). Fall through to the standard bump logic below — the version may still need incrementing if the branch type warrants it.

Standard bump path: If no milestone target version applies, determine the bump type for each matching rule using Semantic Versioning 2.0.0 rules:

1. Check handoff for explicit directive -- if the handoff frontmatter contains version-bump: major|minor|patch|none, use that.
2. Otherwise use the default derived from the branch prefix in Step 5a.
3. Adjust for pre-1.0 -- if the current version is 0.x.y:
   • MAJOR changes become MINOR bumps (0.x.0 -> 0.(x+1).0)
   • MINOR and PATCH stay as-is
4. Adjust for breaking changes -- if the diff introduces incompatible API changes (removed public functions, changed signatures, renamed exports), escalate to MAJOR regardless of the default.

Bump categories:

• MAJOR (X.0.0) -- incompatible API changes
• MINOR (x.Y.0) -- backward-compatible new functionality
• PATCH (x.y.Z) -- backward-compatible bug fixes

4. Apply the bump

A single rule may reference multiple manifest files that must be bumped in sync (joined by "and", e.g. "Bump X and Y in sync"). Parse the rule for all manifest paths mentioned and collect them as a list — each must be bumped to the same new version.

For each manifest file collected from matching rules:

1. Read the version manifest file
2. Parse the current version string based on the manifest format:
   • package.json -- "version": "X.Y.Z"
   • plugin.json -- "version": "X.Y.Z" (same JSON key as package.json)
   • marketplace.json -- each plugin entry contains "version": "X.Y.Z" nested under its plugin key; update the entry whose path corresponds to the plugin being changed
   • Cargo.toml -- version = "X.Y.Z" under [package]
   • pyproject.toml -- version = "X.Y.Z" under [project] or [tool.poetry]
   • setup.cfg -- version = X.Y.Z under [metadata]
   • build.gradle / build.gradle.kts -- version = "X.Y.Z"
   • version.txt -- entire file content is the version string
3. If milestone target version applies: Set the version to the milestone target version directly (do not increment). Apply this same target version to every collected manifest.
4. If standard bump: Apply the computed bump to every collected manifest. Reset lower components (MAJOR resets minor and patch to 0; MINOR resets patch to 0).
5. Write the updated version back to each manifest file.

5. Commit

git add <all-bumped-manifest-files>
git commit -m "chore: bump version to <new-version>"

If multiple manifests were bumped, list all in the commit message:

git add <manifest-1> <manifest-2>
git commit -m "chore: bump versions — <manifest-1> to <v1>, <manifest-2> to <v2>"

Then push the bump commit to the PR branch:

git push origin <branch>

After pushing, switch back to the main branch:

git checkout main

5d. Handle no-op

If no version manifest is found or no versioning rules match, skip the bump silently and proceed to merge.

Step 6: Merge

Ask the user for merge strategy preference (merge commit or squash). If the user has already expressed a preference, use it. Default to merge commit if not specified.

gh pr merge <number> --merge

Or with squash:

gh pr merge <number> --squash

Do not pass --delete-branch — the worktree still holds the branch at this point, so gh would exit with code 1. Remote and local branch cleanup is handled in Step 7.

Step 6b: Complete Linear issue

If integrations.linear is true and a Linear issue ID was found in Step 4b, update the Linear issue after successful merge. All Linear MCP calls must be wrapped in error handling — log a warning on failure but never block the finish pipeline.

1. Mark as Done: Update the Linear issue status to "Done" using mcp__linear__updateIssue.
2. Post a comment: Add a comment to the Linear issue with the merged PR URL using mcp__linear__createComment. Example comment: "Merged in PR # — "

Graceful degradation: if either MCP call fails, log "Warning: Linear MCP unavailable — skipping Linear issue completion." and continue to Step 7.

If integrations.linear is false or no Linear issue was found, skip this step.

Step 7: Clean up local resources

After merge completes:

6a. Update main

git pull origin main

6b. Remove the worktree

Determine the worktree path from the branch name. The convention is .worktrees/<type>-<short-description> where the branch is <type>/<short-description>.

git worktree list

Find the worktree matching the merged branch and remove it:

git worktree remove .worktrees/<folder>

6c. Delete the remote branch

git push origin --delete <branch-name>

If the remote branch was already deleted, this may warn — that is fine.

6d. Delete the local branch

git branch -d <branch-name>

If the branch was already deleted by the merge, this may warn — that is fine.

Step 7: Report completion

Tell the user:

PR # merged and cleaned up. Branch <branch> deleted. Worktree .worktrees/<folder> removed. Lifecycle complete.