Bail
Abandon a feature branch safely by capturing learnings, updating the GitHub issue, closing an open PR, and cleaning worktrees without corrupting main.
Overview
bail is an agent skill most often used in Ship (also Build/pm) that reflects on abandoned work, updates GitHub context, closes PRs if needed, and cleans worktrees safely.
Install
npx skills add https://github.com/camacho/ai-skills --skill bailWhat is this skill?
- Reflect-first protocol before any branch or worktree deletion
- Step detector from issue-only through open PR (steps 0–8)
- Appends structured Bail section to .branch-context.md with reason and learnings
- Disposable clone path to consolidate learnings into MEMORY.md without checking out main in a worktree
- Absolute-path git -C commands for worktree-safe cleanup
- Workflow step detector covers steps 0 through 8 including Ship (PR open)
Adoption & trust: 669 installs on skills.sh; 1 GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
You need to drop a branch or PR but fear silent data loss, a dirty main checkout, or an issue that no longer explains what failed.
Who is it for?
Agents running structured GitHub issue → worktree → PR workflows who must abort without breaking repository hygiene.
Skip if: Repos without GitHub Issues, single-branch hobby projects with no worktrees, or cases where you intend to merge rather than abandon.
When should I use this skill?
Abandoning in-progress issue-driven work and needing reflect-first cleanup of PRs, worktrees, and branches.
What do I get? / Deliverables
Learnings land in .branch-context.md and MEMORY.md, the GitHub issue reflects the bail, and PRs plus worktrees are torn down with absolute-path git safety.
- Updated .branch-context.md with Bail section
- MEMORY.md learnings consolidation
- Closed PR and removed worktree/branch when applicable
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Bail is invoked when shipping or review work stalls—especially with an open PR—so Ship/review is the canonical shelf even though earlier build steps trigger it. Closing PRs, reflecting on failed attempts, and documenting outcomes matches code-review and handoff hygiene rather than greenfield coding.
Where it fits
Stop after orient/isolate when the approach is wrong but you want .branch-context.md updated for the issue.
Close an open PR, record bail reason, and remove the worktree after a failed verification pass.
Document why a production-fix branch was abandoned so the next iteration starts from MEMORY.md notes.
How it compares
Use as a disciplined abort ritual instead of manually deleting branches and losing the narrative on the issue.
Common Questions / FAQ
Who is bail for?
Solo builders and agents using multi-step GitHub + worktree delivery who sometimes must stop and document why instead of forcing a merge.
When should I use bail?
During Build/pm when isolating work goes wrong, during Ship/review when a PR should close without merge, or anytime the workflow detects steps 0–8 and you choose to abort after reflection.
Is bail safe to install?
Review the Security Audits panel on this page; the skill runs git and filesystem commands—verify paths and remotes before letting an agent execute cleanup.
SKILL.md
READMESKILL.md - Bail
Bail-out protocol: always reflect FIRST, then clean up. All commands use absolute paths and `git -C`. ## Inputs - `WORKTREE`: absolute path to current worktree (or primary if no worktree) - Optional reason string (if not provided, ask for one) ## Steps 1. **Detect current step** by examining what exists: | What exists | Estimated step | |------------|---------------| | Just an issue, no branch | Step 0 (Capture) | | .branch-context.md, no worktree | Step 1 (Orient) | | Worktree exists, no code changes | Step 2 (Isolate) | | Plan file on branch | Step 3-4 (Design/Review) | | Code changes committed | Step 5-7 (Build/Verify/Archive) | | PR open on GitHub | Step 8 (Ship) | 2. **Prompt for reason** if not provided. 3. **Write learnings to .branch-context.md** in the worktree: ```bash # Write bail context — use absolute path cat >> "$WORKTREE/.branch-context.md" <<EOF ## Bail - Reason: <reason> - What was attempted: <summary> - What was learned: <learnings> EOF git -C "$WORKTREE" add .branch-context.md git -C "$WORKTREE" commit -m "docs: capture bail context" ``` 4. **Consolidate learnings to MEMORY.md** via disposable clone (never checkout main in a worktree): ```bash BAIL_DIR="${CLAUDE_SESSION_DIR:-$TMPDIR}/bail-reflect" [ -d "$BAIL_DIR" ] && rm -rf "$BAIL_DIR" git clone --depth 50 "$(git -C "$WORKTREE" remote get-url origin)" "$BAIL_DIR" ``` Read `$BAIL_DIR/ai-workspace/MEMORY.md`, append relevant learnings from `.branch-context.md`, then: ```bash git -C "$BAIL_DIR" add ai-workspace/MEMORY.md git -C "$BAIL_DIR" commit -m "docs: consolidate learnings from abandoned <branch> Co-Authored-By: Claude <model>" git -C "$BAIL_DIR" push ``` On non-fast-forward: `git -C "$BAIL_DIR" pull --rebase` then push. Max 3 retries. Clean up: `rm -rf "$BAIL_DIR"` 5. **Update GitHub Issue** (if accessible): ```bash GH_REPO=<owner/repo> gh issue comment <number> --body "Bailing: <reason>. Learnings captured in MEMORY.md." GH_REPO=<owner/repo> gh issue edit <number> --add-label "deferred" --remove-label "triage" ``` 6. **Close PR if open**: ```bash PR_NUM=$(GH_REPO=<owner/repo> gh pr list --head "<branch>" --json number -q '.[0].number') if [ -n "$PR_NUM" ]; then GH_REPO=<owner/repo> gh pr close "$PR_NUM" fi ``` 7. **Ask about branch preservation**: Default: preserve the branch (user can resume later). If user explicitly says delete — confirm by showing what will be destroyed: ``` This will delete: - Branch: <name> - Worktree: <path> - Remote branch (if pushed) Type 'delete' to confirm. ``` Only after typed confirmation: ```bash PRIMARY="$(git -C "$WORKTREE" worktree list --porcelain | grep -m1 '^worktree ' | sed 's/^worktree //')" # Verify branch is merged before deleting (-d fails if unmerged, -D would force) git -C "$PRIMARY" worktree remove "$WORKTREE" git -C "$PRIMARY" branch -d <branch> ``` If `branch -d` fails (unmerged work), warn the user and stop. Do NOT use `branch -D`. 8. **Done.** Do not checkout main — stay in whatever CWD the session has. ## Edge Cases - No worktree exists (bailing at Step 0-1) → skip worktree cleanup, just update issue - No GitHub access → skip issue update, still do local cleanup + memory consolidation - PR already merged → don't close, just note it in the output - No .branch-context.md → create one with just the bail reason before consolidating - `CLAUDE_SESSION_DIR` unset → fall back to `$TMPDIR` for clone Output: Summary of what was cleaned up and where learnings were saved.