finishing-a-development-branch

Name: finishing-a-development-branch
Author: obra

byobra· 95 skills

Installs

146k

Stars

261k

Forks

23k

How to install finishing-a-development-branch?

obra/superpowers/finishing-a-development-branch

$npx -y skills add obra/superpowers --skill finishing-a-development-branch

Installs into the current project.

›Prefer a prompt? Paste this to your agent

Use this skill

Run `npx skills use "https://github.com/obra/superpowers" --skill "obra/superpowers/finishing-a-development-branch"` and follow the generated skill instructions now. Read its complete output, redirecting it to a temporary file first if necessary. Resolve relative paths from the supporting-files directory it provides.

Use the whole pack

Use the skills in "https://github.com/obra/superpowers" that are relevant to the current task. Run `npx skills add "https://github.com/obra/superpowers"` and select the relevant skills, then follow their instructions.

Files · 1

View on GitHub

SKILL.md

1	# Finishing a Development Branch
2
3	## Overview
4
5	Core principle: Verify tests → Detect environment → Present options → Execute choice → Clean up.
6
7	Announce at start: "I'm using the finishing-a-development-branch skill to complete this work."
8
9	## Step 1: Verify Tests
10
11	Run the project's full test suite (`npm test` / `cargo test` / `pytest` / `go test ./...`).
12
13	If tests fail, report the failures and stop — the menu comes after a green suite:
14
15	```
16	Tests failing (<N> failures). Must fix before completing:
17
18	[Show failures]
19	```
20
21	If tests pass: continue to Step 2.
22
23	## Step 2: Detect Environment
24
25	```bash
26	GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
27	GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
28	# Capture now, while still inside the workspace — Step 5 changes directory
29	# before cleanup (Step 6) needs this value
30	WORKTREE_PATH=$(git rev-parse --show-toplevel)
31	```
32
33	This determines which menu to show and how cleanup works:
34
35	\| State \| Menu \| Cleanup \|
36	\|-------\|------\|---------\|
37	\| `GIT_DIR == GIT_COMMON` (normal repo) \| Standard 3 options \| No worktree to clean up \|
38	\| `GIT_DIR != GIT_COMMON`, named branch \| Standard 3 options \| Provenance-based (see Step 6) \|
39	\| `GIT_DIR != GIT_COMMON`, detached HEAD \| Reduced 2 options (no merge) \| Externally managed — leave in place \|
40
41	## Step 3: Determine Base Branch
42
43	The base branch is whatever this work forked from — usually named in the
44	plan, the conversation, or the branch's upstream. If it is not already
45	known, ask: "This branch split from <your best guess> - is that correct?"
46	Confirm before merging: merging into the wrong base is expensive to undo.
47
48	## Step 4: Present Options
49
50	Normal repo and named-branch worktree — present exactly these 3 options:
51
52	```
53	Implementation complete. What would you like to do?
54
55	1. Merge back to <base-branch> locally
56	2. Push and create a Pull Request
57	3. Keep the branch as-is (I'll handle it later)
58
59	Which option?
60	```
61
62	Detached HEAD — present exactly these 2 options:
63
64	```
65	Implementation complete. You're on a detached HEAD (externally managed workspace).
66
67	1. Push as new branch and create a Pull Request
68	2. Keep as-is (I'll handle it later)
69
70	Which option?
71	```
72
73	Present the menu exactly as written — concise, with every option coming
74	from the list above. Discarding the work happens only in response to your
75	human partner explicitly asking for it (see "If your human partner asks to
76	discard the work" below). Wait for their answer; the integration decision
77	is theirs.
78
79	## Step 5: Execute Choice
80
81	### Option 1: Merge Locally
82
83	```bash
84	# Get main repo root for CWD safety
85	MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
86	cd "$MAIN_ROOT"
87
88	# Merge first — verify success before removing anything
89	git checkout <base-branch>
90	git pull
91	git merge <feature-branch>
92
93	# Verify tests on merged result
94	<test command>
95	```
96
97	If tests fail on the merged result: stop, leave the worktree and branch in
98	place, and investigate — nothing has been pushed, so the merge is local
99	and recoverable.
100
101	Once the merged result is green: clean up the worktree (Step 6), then
102	delete the branch:
103
104	```bash
105	git branch -d <feature-branch>
106	```
107
108	### Option 2: Push and Create PR
109
110	```bash
111	git push -u origin <feature-branch>
112	# From a detached HEAD, name the new branch on the remote:
113	# git push origin HEAD:refs/heads/<new-branch>
114	```
115
116	Then create the pull/merge request against <base-branch> with the forge's
117	tooling — its CLI if one is available, or the creation URL most forges
118	print when you push — following the repo's PR template and conventions if
119	present, and report the URL to your human partner.
120
121	Keep the worktree — your human partner iterates on PR feedback there.
122
123	### Option 3: Keep As-Is
124
125	Report: "Keeping branch <name>. Worktree preserved at <path>."
126
127	### If your human partner asks to discard the work
128
129	This path exists only as a response to an explicit request to throw the
130	work away. Confirm first:
131
132	```
133	This will permanently delete:
134	- Branch <name>
135	- All commits: <commit-list>
136	- Worktree at <path>
137
138	Type 'discard' to confirm.
139	```
140
141	Wait for that exact confirmation. When it arrives:
142
143	```bash
144	MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
145	cd "$MAIN_ROOT"
146	```
147
148	Then clean up the worktree (Step 6) and force-delete the branch:
149
150	```bash
151	git branch -D <feature-branch>
152	```
153
154	## Step 6: Cleanup Workspace
155
156	Runs for Option 1 and confirmed discards. Options 2 and 3 always
157	preserve the worktree. Both callers have already changed directory to the
158	main repo root — worktree removal must run from outside the worktree —
159	and use the `GIT_DIR`/`GIT_COMMON`/`WORKTREE_PATH` values captured in
160	Step 2, from before that directory change.
161
162	If `GIT_DIR == GIT_COMMON`: Normal repo, no worktree to clean up. Done.
163
164	If `WORKTREE_PATH` is under `.worktrees/` or `worktrees/`: Superpowers
165	created this worktree — we own cleanup:
166
167	```bash
168	git worktree remove "$WORKTREE_PATH"
169	git worktree prune # Self-healing: clean up any stale registrations
170	```
171
172	Otherwise: The host environment owns this workspace — leave it in
173	place. If your platform provides a workspace-exit tool, use it.
174
175	## Quick Reference
176
177	\| Option \| Merge \| Push \| Keep Worktree \| Cleanup Branch \|
178	\|--------\|-------\|------\|---------------\|----------------\|
179	\| 1. Merge locally \| yes \| - \| - \| yes \|
180	\| 2. Create PR \| - \| yes \| yes \| - \|
181	\| 3. Keep as-is \| - \| - \| yes \| - \|
182	\| Discard (explicit request only) \| - \| - \| - \| yes (force) \|
183
184	## Common Rationalizations
185
186	\| Excuse \| Reality \|
187	\|--------\|---------\|
188	\| "Tests passed earlier this session" \| Run the suite on the tree you are about to integrate. A green run only proves the tree it ran on. \|
189	\| "They obviously want it merged" \| Integration is your human partner's decision. Present the menu and wait. \|
190	\| "They seem done with this feature — I'll offer to discard it" \| The menu is complete as written. Discard happens only when your human partner asks for it in so many words. \|
191	\| "'Yeah, get rid of it' counts as confirmation" \| Only the typed word `discard` authorizes deletion. \|
192	\| "The PR is up, so the worktree is clutter now" \| PR feedback gets fixed in that worktree. It stays until the work lands. \|
193	\| "This other worktree looks stale — I'll clean it too" \| Clean up only worktrees under `.worktrees/` or `worktrees/`. Everything else belongs to the host. \|
194	\| "The merged-result failure is probably flaky" \| A failing merged result stops everything. Branch and worktree stay put while you investigate. \|
195	\| "The base branch is obviously main" \| Confirm the fork point or ask. Merging into the wrong base is expensive to undo. \|
196	\| "The push was rejected — force-push will fix it" \| A rejected push means the remote moved. Investigate; force-push only on your human partner's explicit request. \|

6 picks

Type

Run `npx skills use "https://github.com/obra/superpowers" --skill "obra/superpowers/finishing-a-development-branch"` and follow the generated skill instructions now. Read its complete output, redirecting it to a temporary file first if necessary. Resolve relative paths from the supporting-files directory it provides.

Use the skills in "https://github.com/obra/superpowers" that are relevant to the current task. Run `npx skills add "https://github.com/obra/superpowers"` and select the relevant skills, then follow their instructions.

finishing-a-development-branch

How to install finishing-a-development-branch?

Related

finishing-a-development-branch

How to install finishing-a-development-branch?

Related