How do I start a new feature branch phase?

Question
Answer
Conventions
Script
Tested by
See also

For the surrounding skill (when this fits in the workflow and how many phases to plan for), see Feature Branch Manager.

Question

The current phase's PR has merged. How do I cleanly start the next phase on a fresh branch, without losing in-flight work or leaving stale branches behind?

Answer

The procedure preserves uncommitted work, branches from the post-merge main, and removes the old branch locally and remotely.

Note the current branch for cleanup later:
```
git branch --show-current
```
Confirm the current PR has merged. Do not transition before merge:
```
gh pr view --json state,mergedAt
```
state: MERGED and a populated mergedAt mean it's safe to move on. If gh isn't available:
```
git fetch origin main
git branch --contains "$(git rev-parse HEAD)" -r | grep origin/main
```

Stash any uncommitted changes:

git status --short
git stash push -m "WIP: transitioning to next phase"

Fetch the latest main (the gh path skipped this; the git fallback already did it):
```
git fetch origin main
```
Create the new branch from the freshly-fetched main:
```
git checkout -b feature/<entity>_<next_phase> origin/main
```
Branch naming follows feature/<entity>_<phase_description> — e.g. feature/currency_generator, feature/session_history_dialog.
Restore the stash, if any:
```
git stash pop
```
If pop produces conflicts, resolve before continuing.
Delete the old local branch:
```
git branch -d <old-branch-name>
```
Use -D only if the branch was abandoned without merge (rare).

Delete the old remote branch:

git push origin --delete <old-branch-name>

Conventions

Always branch from fresh main — each phase includes all prior phases' merged work.
Never rebase + force-push — confuses reviewers and can break protected-branch policy.
Delete after merge — keeps both ends of the remote clean.
Hotfix branches — emergency fixes use hotfix/<broken-thing>, created with compass story new --slug <broken_thing> --kind hotfix. They are branched from fresh main and follow the same PR process. The story lands in the sprint's ** Hotfixes section. See Handle a hotfix for the full procedure.

Script

Bare git + gh CLI.

Tested by

Manual. Catches in CI are limited to "did the branch get pushed successfully"; the workflow correctness is held by review.