branch-preflight — Catch inherited working-tree damage early

When to invoke

Trigger this skill BEFORE any of:

• Starting plan execution (superpowers:executing-plans, superpowers:subagent-driven-development)
• Creating a new feature branch off main (git switch -c feat/...)
• Investigating a verification failure on files you do not recognize as yours

You should also volunteer to run it if the user mentions:

• "let's start implementing"
• "execute the plan"
• "kick off the work"

Why it exists

Damage inherited from main (conflict markers committed to a tracked file, a forgotten autostash, stray uncommitted edits) surfaces later as an unrelated parse or test failure partway through a plan, forcing an out-of-plan fix. This script catches that class of damage in under a second, before any plan step depends on a clean tree.

What it checks

1. Merge conflict markers in tracked files. Greps git ls-files for <<<<<<<, =======, or >>>>>>> line prefixes. Tracked-files-only avoids false positives on .Codex/ scratch notes.
2. Stash entries. A non-empty git stash list is a yellow flag — most users don't realize an autostash is sitting there.
3. Uncommitted changes. Surfaces both unstaged (git diff) and staged (git diff --cached) work.

How to use

Just run it:

bash scripts/branch-preflight.sh

Exit code:

• 0 — clean, safe to proceed
• 1 — at least one finding; review the output before starting

What to do with findings

Out of scope

This script does NOT check:

• Whether the branch is up to date with main (use git fetch && git status)
• Whether dependencies are installed (use bun install)
• Whether tests currently pass (use bun run test)
• Whether CI is green for the branch (use gh pr checks)

These are different problems with different feedback loops. This skill is the cheapest possible "is the working tree sane?" check.

Gotchas

• The merge-marker grep uses ^<<<<<<< / ^>>>>>>> / ^={7}$ regex anchored at line start, so it won't false-positive on documentation that mentions conflict markers in prose.
• The stash check counts ALL stash entries, including ones from other tools (autostash from git pull --rebase, IDE auto-stashes). It's a yellow flag, not a red one — the script exits non-zero but the message says "acknowledge before starting", not "fix immediately".