# Finishing A Development Branch

> Use when implementation is complete, all tests pass, and you need to decide how to integrate the work - guides completion of development work by presenting structured options for merge, PR, or cleanup

- Skill: `mrlyk/finishing-a-development-branch` (Agent Skill)
- Install (CLI): `npx skillmds@latest add mrlyk/finishing-a-development-branch`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mrlyk/finishing-a-development-branch/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: mrlyk (https://skillmd.com/u/mrlyk)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/mrlyk/finishing-a-development-branch

---


# Finishing a Development Branch

**Core principle:** check phase -> review discipline confirmed -> final test gate -> verification evidence -> complete -> durable evidence commit -> delivery options.

**Announce at start:** "I'm using the finishing-a-development-branch skill to complete this work."

For `"profile": "lite"` tasks: same check-phase final verification and durable evidence contract. After completion, offer once to generate or refresh the tester handoff (`superharness:to-tester {task}`) and the developer report (`superharness:to-coder {task}`); if both are declined, finish. Skip the full option menu (Steps 5-8). Worktree cleanup (Step 9) applies only if a worktree was actually created.

## Step 1: Confirm Check Inputs

Read `task.json` first. On the normal path the task is still in `check` when finishing starts. Entry discipline — all three must hold, or return to the Final Check in `superharness:subagent-driven-development` first:

- The two-axis review reports were produced in this session (rerun one two-axis review if the session lost them).
- Every Critical/Major finding is resolved.
- Every code commit after the **reviewed HEAD** has a fix-diff recheck verdict.

Recovery is phase-aware:

- In `check`, when `verification.md` already records this same Verified Implementation HEAD with every command passing, resume at Step 4 without rerunning the full gate.
- In `complete`, when completion changed only `task.json` and `trace.jsonl` and the matching successful `verification.md` is still uncommitted, resume the Step 4 evidence commit.
- In `complete` otherwise, run `superharness task evidence {task} --json`; a valid chain continues to delivery options. Any other phase or evidence shape stops for diagnosis.

For a new verification run: `git rev-parse HEAD` is the **Verified Implementation HEAD**; it must equal the review's effective HEAD. `Base` comes from `implementation.base_sha`. Confirm every implementation, test, documentation, and configuration change is committed; the only permitted dirty paths are the task's `task.json`, `trace.jsonl`, and an existing `verification.md`. Any other dirty path returns through `check → implement` for a tested implementation commit.

## Step 2: Run the Final Test Gate

Run the project's full non-E2E gate exactly once for the captured HEAD: the full unit/integration suite plus configured typecheck, lint, skill validation, and build commands, **plus** every task's focused verification command and every `verified` slice's declared gate (independent integration commands, E2E cases, contract checklist items), deduplicated and executed or confirmed once each. QA remains an optional delivery step.

Record one global `superharness task observe {task} verification-start --detail full` immediately before the first command. After every command passes, close with one `verification-pass`. On a command failure record `verification-fail --detail "<failed command>"`; on an environment error record `verification-error --detail "<error>"`. One global pair per attempt.

Before running tests, clean up leftover E2E processes from a previous QA run:

```bash
if [ -f ".superharness/tasks/{task}/.e2e-app.pid" ]; then
  superharness e2e stop-app --pid-file .superharness/tasks/{task}/.e2e-app.pid --port {port}
  agent-browser close 2>/dev/null || true
fi
```

Capture every exact command, exit code, and concise result. Do not reuse results from focused tests or the review session.

If any command fails: `superharness task transition {task} implement`, fix through TDD, commit, `superharness task transition {task} check`, recheck the fix diff (do not repeat the full two-axis review), then invoke finishing again for a new full gate.

## Step 3: Replace Verification Evidence

Rewrite `.superharness/tasks/{task}/verification.md` for every new verification run, including a failed one, so it describes only this HEAD and this run. Use this exact schema:

````markdown
# Verification

- Timestamp: <ISO>
- Verified Implementation HEAD: <sha>
- Base: <sha>

## Commands

- `<exact command>`: exit <code>; <concise result>

## Final Review

- Two-axis outcome and resolved Critical/Major findings; remaining Minor findings.
- Reviewed HEAD: <sha>
- Post-review fix commits, each with its fix-diff recheck verdict, or `None`.
- Effective HEAD: <sha> (must equal the Verified Implementation HEAD)

## QA Evidence

- Revision-bound QA run, verdict, decision, or `Not run`.

## Unverified

- Items not covered by the commands or review, or `None`.

## Known Risks

- Remaining risks, or `None`.
````

Read the file back and confirm it matches the current run. Any repair invalidates prior evidence and requires one new full gate.

## Step 4: Complete and Commit Durable Evidence

Only after every command passes:

```bash
superharness task transition {task} complete
git add -- .superharness/tasks/{task}/task.json .superharness/tasks/{task}/trace.jsonl .superharness/tasks/{task}/verification.md
git diff --cached --name-only
git commit -m "chore(workflow): record final verification evidence"
```

The staged diff must contain exactly those three task files. Every descendant of the Verified Implementation HEAD may touch only them. Then run `superharness task evidence {task} --json`; the chain must report the recorded implementation HEAD with only evidence-only descendants. Do not offer delivery choices until the chain is valid and the worktree is clean. Then read `task.json`, `verification.md`, Git, optional QA evidence, and `trace.jsonl`; run `superharness trace --task {task}`.

## Step 5: Determine Base Branch

```bash
git merge-base HEAD main 2>/dev/null || git merge-base HEAD master 2>/dev/null
```

Or ask: "This branch split from main -- is that correct?"

## Step 6: Determine Optional QA Availability

QA is a user-selected post-complete action, never a completion gate. Set `qaAvailable=true` only when `.superharness/tasks/{task}/e2e-cases.yaml` exists or `.superharness/config.yaml` has at least one enabled `qa.services` entry.

## Step 7: Present Options

```text
Implementation complete. Reviewed .superharness/tasks/{task}/trace.jsonl.

What would you like to do?

1. Run QA verification (includes discovered E2E)
2. Generate or refresh tester handoff
3. Generate or refresh developer report
4. Merge back to <base-branch> locally
5. Push and create a Pull Request
6. Keep the branch as-is (I'll handle it later)
7. Discard this work

Which option?
```

When `qaAvailable=false`, omit item 1 and renumber. Keep options concise.

## Step 8: Execute Choice

- **Run QA:** `superharness qa --task .superharness/tasks/{task}`. Pass or accept-risk transitions back to complete, creates an evidence-only commit, validates `task evidence`, then returns to Step 7. A fix decision: persist it, transition to implement, land the repair commit, transition to check, recheck the fix diff, run fresh non-E2E verification, complete with a new evidence chain, then automatically rerun QA without asking.
- **Tester handoff:** invoke `superharness:to-tester {task}`, then return to Step 7.
- **Developer report:** invoke `superharness:to-coder {task}`, then return to Step 7.
- **Merge locally:** checkout the base branch, pull, merge, verify tests on the merged result, delete the feature branch, then clean up the worktree (Step 9).
- **Push and create PR:** `git push -u origin <branch>`, then `gh pr create` with a summary, evidence summary (task item commits, final review, verification commands), and test plan. Clean up the worktree (Step 9).
- **Keep as-is:** report "Keeping branch <name>. Worktree preserved at <path>." Do not clean up. The task stays completed — that is correct even though the branch persists.
- **Discard:** confirm first with the exact typed word `discard` (or `确认丢弃`), listing the branch, commits, and worktree to delete. If confirmed: checkout the base branch, `git branch -D <branch>`, then in the base checkout run `superharness task transition {task} discarded` (a terminal status like `completed`), and clean up the worktree (Step 9).

## Step 9: Cleanup Task Worktree

For Merge, Create PR, and Discard: `git worktree remove <worktree-path>`. For Keep as-is, QA, tester handoff, and developer report: keep the worktree — the user's delivery choice controls the single task checkout.

## Red Flags

**Never:**

- Proceed with failing tests, or merge without verifying tests on the result
- Report completion without durable evidence: a valid `task evidence` chain plus `task.json`, `verification.md`, Git, QA, and `trace.jsonl` read back
- Present options while workflow evidence is uncommitted or the worktree is dirty
- Treat E2E cases as a completion prerequisite
- Delete work without typed confirmation, or force-push without explicit request
- Bind evidence to a HEAD whose post-review commits lack fix-diff rechecks