finalizing-workflow

name	finalizing-workflow
description	Merges the current PR, checks out main, fetches, and pulls — reducing the repetitive end-of-workflow sequence to a single slash command. Use when the user says "finalize", "merge and reset", "finalize workflow", or after QA passes.
allowed-tools	["Bash"]

Finalizing Workflow

Merge the current PR and reset to main in one invocation. Terminal step in all three SDLC chains.

When to Use This Skill

• User says "finalize", "finalize workflow", "merge and reset", or "wrap up"
• After QA passes and the PR is ready to merge
• User wants to merge the current branch's PR and return to main

Workflow Position

Features: ... → implementing-plan-phases → executing-qa → finalizing-workflow
Chores:   ... → executing-chores        → executing-qa → finalizing-workflow
Bugs:     ... → executing-bug-fixes     → executing-qa → finalizing-workflow

Output Style

Follow the lite-narration rules below. Load-bearing carve-outs MUST be emitted as specified; they are not narration. This skill is small and mostly mechanical (gh and git commands wrapped by finalize.sh) — the rules should be easy to honor here.

Lite narration rules

• No preamble before tool calls. Do not announce "let me check" or "I'll run" -- issue the tool call.
• No end-of-turn summaries beyond one short sentence. Do not recap what the user can read from tool output (e.g., the verbatim finalize.sh report).
• No emoji. ASCII punctuation only.
• No restating what the user just said.
• No status echoes that tools already show (e.g., the contents of a successful git status).
• Prefer ASCII arrows (->) and punctuation over Unicode alternatives in skill-authored prose. Existing Unicode em dashes in tables and reference docs are retained. Script-emitted structured logs are out of scope — finalize.sh stdout and [error] / [warn] stderr lines use their documented format and must be surfaced verbatim.
• Short sentences over paragraphs. Bullet lists over prose when listing more than two items.

Load-bearing carve-outs (never strip)

The following MUST always be emitted even when they resemble narration:

• Error messages from fail calls -- users need the reason the skill halted. Surface finalize.sh stderr verbatim.
• Security-sensitive warnings -- destructive-operation confirmations, credential prompts.
• Interactive prompts -- the single "Ready to merge PR #<N> ..." confirmation prompt is required and blocks the workflow; it must be visible.
• Findings display from reviewing-requirements -- N/A for this skill (it does not consume reviewing-requirements findings); bullet retained for consistency with the canonical template.
• FR-14 console echo lines -- [model] step {N} ({skill}) → {tier} (...) audit-trail lines emitted by prepare-fork.sh. The Unicode → is the documented emitter format; do not rewrite to ASCII.
• Tagged structured logs -- any line prefixed [info], [warn], or [model] is a structured log, not narration. Emit verbatim.
• User-visible state transitions -- pause, advance, and resume announcements (at most one line each).

Fork-to-orchestrator return contract

This skill is forked by orchestrating-workflows as the terminal step of every chain (feature chain step 5+N+4; chore and bug chain step 7). Emit done | artifact=<note-or-empty> | <note-of-at-most-10-words> as the final line on success, and failed | <one-sentence reason> on failure. The Found **N errors**, **N warnings**, **N info** shape is reserved for reviewing-requirements only and MUST NOT be emitted here.

Precedence: the return contract takes precedence over the lite rules when the two conflict. The subagent MUST emit the contract shape as the final line of the response even if it reads like narration.

Write Surface

Allowed paths: requirements/{features,chores,bugs}/<ID>-*.md only. Allowed operations: gh pr merge, git checkout main, git fetch, git pull, and a bookkeeping git add + commit of the requirement doc. Forbidden: git rm, git mv, rm, git restore --staged, and content edits outside that surface.

If preflight-checks.sh blocks the merge, surface the stderr verbatim and return failed | preflight blocked: <reason>. Do NOT delete or rename any file to unblock the merge. finalize.sh enforces this itself: it arms a baseline at start (scripts/arm-baseline.sh) and runs a pre-merge guard (scripts/check-write-surface.sh) on the feature branch BEFORE the merge dispatch, aborting (exit 1) if any committed (baseline..HEAD), staged, or working-tree change touched a path outside the surface. The check lives in the script the fork runs — not a Stop hook, which never fires for a forked subagent.

Usage

Capture the branch, confirm intent up-front, then delegate the full sequence (pre-flight, bookkeeping, merge, reset) to finalize.sh:

1. Capture the branch: branch=$(git branch --show-current).

2. Fetch PR number and title for the prompt via the managing-source-control dispatcher: bash "${CLAUDE_PLUGIN_ROOT}/skills/managing-source-control/scripts/view-pr.sh". Display only — the real pre-flight (clean tree, PR state, mergeability) runs inside finalize.sh.

3. Ask the user exactly once:

   Ready to merge PR #<N> ("<title>") and finalize the requirement document. Proceed?

4. On no / n / empty, abort before invoking the script and report Aborted — no changes made. Do not run finalize.sh.

5. On confirmation, run the script:

   bash "${CLAUDE_PLUGIN_ROOT}/skills/finalizing-workflow/scripts/finalize.sh" "$branch"
   

   finalize.sh self-arms the write-surface baseline and runs the pre-merge guard internally — no marker preamble is needed. If finalize.sh exits non-zero, surface its stderr verbatim and return failed | preflight blocked: <reason>. Do NOT run any git mutation to recover.

finalize.sh does not prompt — confirmation is owned entirely by this skill. The script runs unattended after confirmation.

Expected output

On success (exit 0), the script prints a short multi-line report: merged PR number and title, a Bookkeeping: summary line (ran / skipped with reason), an optional Pushed bookkeeping commit as <sha> line when the requirement doc was updated, and a final On main, up to date line. Surface stdout verbatim.

On non-zero exit, finalize.sh emits a single [error] (or [warn]) stderr line describing the failure (pre-flight abort, push failure, merge failure, etc.). Surface that stderr verbatim — it is the sole error surface.

Relationship to Other Skills

Terminal step in all workflow chains. Reconciliation steps are optional but recommended.

Task	Recommended Approach
Document requirements	Use documenting-features, documenting-chores, or documenting-bugs
Review requirements	Use reviewing-requirements
Build QA test plan	Use documenting-qa
Reconcile after QA plan creation	Use reviewing-requirements — test-plan reconciliation mode (optional but recommended)
Create implementation plan	Use creating-implementation-plans
Implement the plan	Use implementing-plan-phases
Execute chore or bug fix	Use executing-chores or executing-bug-fixes
Reconcile after PR review	Use reviewing-requirements — code-review reconciliation mode (optional but recommended)
Execute QA verification	Use executing-qa
Merge PR and reset to main (and finalize requirement doc)	Use this skill (finalizing-workflow)