finishing-a-development-branch

Overview of finishing-a-development-branch skill

The finishing-a-development-branch skill is a narrow workflow helper for the moment when coding is done and you need to close out a Git branch cleanly. Its job is not to help you implement features; it helps you decide and execute the next branch-ending step only after confirming the work is actually ready.

What the finishing-a-development-branch skill does

This skill enforces a simple completion sequence:

1. verify tests pass
2. determine the correct base branch
3. present a short set of end-of-branch options
4. execute the chosen path or stop safely

That makes it useful when an agent might otherwise jump straight to merging, opening a PR, or deleting work without checking readiness first.

Who should use this skill

Best fit readers for the finishing-a-development-branch skill are:

• developers using AI to help with Git workflows
• maintainers who want branch completion handled consistently
• agents that should avoid making merge decisions too early
• users who want a repeatable “done means done” prompt for branch wrap-up

It is especially helpful in repos where multiple completion paths are valid and the right next step depends on team practice.

Real job-to-be-done

The real problem this skill solves is not “how do I run git merge.” It is: “implementation appears complete, tests should gate the next move, and I need a structured decision instead of an improvised Git action.”

That distinction matters because many bad branch finishes happen before anyone confirms tests, base branch, or whether the work should be merged, pushed, kept, or discarded.

Why this skill stands out for Git workflows

For finishing-a-development-branch for Git Workflows, the biggest differentiator is restraint. The skill does not try to infer a full release strategy or invent custom branching policy. It gives a tight workflow with a clear stop condition when tests fail.

That makes it better than a generic prompt when you want predictable branch completion behavior rather than broad advice.

What matters most before you install

The main adoption questions are simple:

• does your workflow actually end with tests as a gate?
• do you want exactly four completion choices, not a custom branching framework?
• are you comfortable with a skill that may stop and ask instead of acting immediately?

If yes, the finishing-a-development-branch skill is a good fit. If you want a richer PR template, release notes generation, or complex CI/CD orchestration, this skill is intentionally too small.

How to Use finishing-a-development-branch skill

Install context for the finishing-a-development-branch skill

The upstream skill lives in the obra/superpowers repository under skills/finishing-a-development-branch. If your skill runner supports adding a skill from a GitHub repo, a common pattern is:

npx skills add https://github.com/obra/superpowers --skill finishing-a-development-branch

If your environment uses a different installer, the key point is the skill path and slug: finishing-a-development-branch.

Read this file first

Start with:

• skills/finishing-a-development-branch/SKILL.md

This skill is self-contained. There are no extra rules/, resources/, or helper scripts to learn first, so your install decision should be based almost entirely on whether the SKILL.md workflow matches your branch-closing process.

When to invoke finishing-a-development-branch usage

Use finishing-a-development-branch usage only when all of these are true:

• implementation work is complete enough to evaluate
• you are ready to run or review tests
• you want a branch-ending action, not more coding
• you know the repository is in a state where Git actions can be taken safely

Do not invoke it while requirements are still changing or while test failures are still being debugged.

What input the skill needs

To work well, the skill needs a small but important set of context:

• the current branch
• the likely base branch, if known
• how to run the project test suite
• whether pushing or PR creation is allowed in your environment
• whether destructive actions like branch deletion are permitted

Without that context, an agent can still follow the flow, but it will need to ask more questions before acting.

The expected workflow inside the skill

The skill’s internal sequence is straightforward:

1. run the project’s test suite
2. stop if tests fail
3. determine the base branch, often main or master
4. present exactly four options:
   • merge back locally
   • push and create a Pull Request
   • keep the branch as-is
   • discard the work
5. execute the selected option

This is why the skill is useful: it turns a vague “finish this branch” request into a gated decision flow.

How to turn a rough goal into a strong prompt

Weak prompt:

Finish this branch.

Stronger prompt:

Use the finishing-a-development-branch skill. The current branch is feature/search-filters. It should merge back to main if tests pass. Run the repo test suite with pytest. If everything passes, show me the standard completion options and wait for my choice before pushing, opening a PR, or deleting anything.

Why this is better:

• it explicitly invokes the skill
• it supplies the test command
• it states the likely base branch
• it tells the agent to pause for a decision instead of assuming one

Strong prompt examples for common paths

For local merge:

Use the finishing-a-development-branch skill for this repo. Current branch: `fix/login-timeout`. Base branch should be `main`. Run `npm test` first. If tests pass, offer the normal options and be prepared to merge locally if I choose option 1.

For PR-oriented teams:

Use the finishing-a-development-branch skill. We use Pull Requests, not direct merges. Run `go test ./...`, confirm the base branch, then present the normal four options. If I choose PR, push the branch and prepare the PR creation step.

For cautious review:

Use the finishing-a-development-branch skill, but do not push, merge, discard, or delete branches without confirming with me after tests pass.

Practical tips that improve output quality

A few details make the finishing-a-development-branch guide much more reliable in practice:

• provide the exact test command instead of expecting auto-detection
• say whether main, master, or another branch is the expected base
• state whether branch deletion is allowed after merge
• tell the agent whether PR creation should be local-only guidance or executed against a remote

Most errors at this stage come from missing repo-specific policy, not from Git itself.

What to expect when tests fail

This skill is intentionally conservative. If tests fail, it should stop and report that completion cannot proceed yet. That behavior is a feature, not friction.

If your actual need is “fix failing tests, then finish the branch,” use a separate implementation or debugging prompt first, then come back to finishing-a-development-branch install and usage once the branch is healthy.

Repository-reading path before adoption

If you are evaluating rather than actively using the skill, read in this order:

1. SKILL.md overview
2. the test verification step
3. the exact four-option prompt
4. the execution logic for your preferred path

That tells you almost everything important: whether the gating is strict enough, whether the choice set matches your workflow, and whether the skill is too opinionated or not opinionated enough.

finishing-a-development-branch skill FAQ

Is the finishing-a-development-branch skill only for advanced Git users?

No. It is beginner-friendly because it narrows the task to a small decision tree. The main requirement is that you understand the consequences of the four options, especially merge and discard.

Beginners may still want to require confirmation before any destructive action.

How is this different from a normal prompt like “wrap this up”?

A normal prompt often skips key safeguards. The finishing-a-development-branch skill gives you:

• a required test check first
• a base-branch check
• a fixed menu of next actions
• a cleaner handoff from “coding” to “integration”

That reduces guesswork and makes the agent less likely to improvise risky Git actions.

When is this skill a bad fit?

Skip it if you need:

• release branching strategy
• squash/rebase policy enforcement beyond the basic flow
• CI pipeline design
• commit history cleanup as the main task
• a fully customized PR authoring workflow

This skill is about finishing a development branch, not managing the entire delivery lifecycle.

Does it work for teams that require Pull Requests?

Yes, as long as PR creation is one of your accepted completion paths. In fact, teams with stricter review policies often benefit more because the skill forces a test-first checkpoint before the PR step.

Can the skill decide the best option automatically?

It is better at presenting the options than choosing one for you. The design favors explicit user choice after readiness checks. That is usually safer for Git workflows than silent automation.

Do I need to know the base branch in advance?

Not always. The skill includes a step to determine or confirm the base branch. Still, you get better results if you provide it up front, especially in repos with long-lived release or integration branches.

How to Improve finishing-a-development-branch skill

Give the skill branch policy upfront

The fastest way to improve finishing-a-development-branch results is to tell the agent your actual branch rules before it starts. Useful examples:

• direct merges to main allowed: yes or no
• PR required: yes or no
• delete branch after merge: yes or no
• force push allowed: yes or no

This prevents the skill from offering technically possible but policy-wrong actions.

Provide the exact test command, not just “run tests”

The skill’s first gate is test verification, so ambiguous test instructions create avoidable friction. Better inputs look like:

• npm test
• pytest
• cargo test
• go test ./...

If the repo needs setup, include that too. Example:

Use the finishing-a-development-branch skill. Run `python -m pytest tests/unit` from the repo root after `uv sync`.

Clarify what “done” means before invoking the skill

A common failure mode is calling the skill before the work is actually complete. Improve results by stating:

• feature complete
• docs complete or intentionally skipped
• tests added or not needed
• migration or config changes already handled

That keeps the skill focused on branch completion rather than reopening implementation discussion.

Reduce risky behavior with confirmation rules

If you want safer finishing-a-development-branch usage, tell the agent what requires confirmation. For example:

Ask before any push, PR creation, merge, branch deletion, or discard action, even if tests pass.

This is especially valuable in shared repos or when using an agent with shell access.

Handle the biggest failure mode: wrong base branch

One of the most expensive mistakes in branch finishing is merging into the wrong target. Prevent that by supplying one of these stronger inputs:

• Assume the base branch is main unless merge-base shows otherwise
• This branch was created from release/2.4
• If base branch is ambiguous, ask before continuing

This one line often improves output quality more than extra Git detail.

Iterate after the first output instead of restarting

If the first pass is close but not right, do not throw it away. Refine it with concrete corrections:

• “Use develop, not main.”
• “Offer PR only; local merge is not allowed here.”
• “Do not suggest discard for protected branches.”
• “Run integration tests too, not just unit tests.”

The skill’s structure is simple enough that small corrections usually produce much better second-pass behavior.

Improve adoption by pairing it with adjacent skills or prompts

The finishing-a-development-branch skill works best after the implementation phase is already settled. A practical pattern is:

1. use coding or debugging help until tests pass
2. invoke finishing-a-development-branch
3. use a separate PR-writing or review prompt only if you choose the PR path

That separation keeps branch completion focused and avoids bloating this skill with unrelated release tasks.