/workflow:preflight
Pre-work validation to prevent wasted effort from stale state, redundant work, or branch conflicts.
When to Use This Skill
| Use this skill when... | Skip when... |
|---|---|
| Starting work on a new issue or feature | Quick single-file edit |
| Resuming work after a break | Already verified state this session |
| Before spawning parallel agents | Working in an isolated worktree |
| Before creating a branch for a PR | Branch already created and verified |
Context
- Repo: !
git remote -v - Current branch: !
git branch --show-current - Remote tracking: !
git branch -vv --format='%(refname:short) %(upstream:short) %(upstream:track)' - Uncommitted changes: !
git status --porcelain - Stash count: !
git stash list
Execution
Run the preflight check, then apply judgment to its results.
Step 1: Gather preflight state
Invoke the gatherer. Pass --issue <n> or --branch <name> when the argument
is a GitHub issue number or branch:
bash "${CLAUDE_SKILL_DIR}/scripts/preflight.sh" --project-dir "$(pwd)" [--issue N] [--branch NAME]
The script fetches origin --prune, resolves the base ref (origin/main →
origin/master → main → master), and emits a structured KEY=VALUE block:
AHEAD / BEHIND divergence, UNCOMMITTED / STASH_COUNT, CONFLICTS
(+ CONFLICT_FILES), existing-work lookups (ISSUE_STATE, EXISTING_PRS,
BRANCH_MATCHES), and a fixed RECOMMENDATION. It degrades gracefully when
gh is unavailable (GH_AVAILABLE=false) and never fails on network errors.
Pass --base <ref> to override the comparison ref, --no-fetch to skip the
network round-trip.
Step 2: Act on existing work (judgment)
Read EXISTING_PRS (#N:STATE:headRef entries) and RECOMMENDATION:
RECOMMENDATION=already-addressed(a:MERGED:PR exists): report that the issue is already addressed and stop — do not duplicate the work.RECOMMENDATION=existing-pr(an:OPEN:PR exists): report the PR and ask the user whether to continue on that branch or start fresh (AskUserQuestion). Do not pick for them.- Otherwise continue to the summary.
Step 3: Summary report
Translate the KEY=VALUE block into a summary the user can act on:
| Check | Source key | Detail |
|---|---|---|
| Remote state | FETCH | ok / skipped / no-remote |
| Existing PRs | EXISTING_PRS | PR numbers + state, if any |
| Branch state | AHEAD / BEHIND / UNCOMMITTED | ahead/behind counts, dirty tree |
| Conflicts | CONFLICTS / CONFLICT_FILES | conflicting files |
| Stash | STASH_COUNT | number of stash entries |
Lead with the headline RECOMMENDATION, then surface every relevant note —
the recommendation is a single first-match headline, but multiple conditions
can be worth mentioning:
RECOMMENDATION | Tell the user |
|---|---|
resolve-conflicts | Resolve conflicts with the base ref before proceeding |
commit-or-stash | Commit or stash changes before branching |
rebase | Rebase on the base ref before starting work |
existing-pr | A PR already addresses this — review before duplicating |
already-addressed | A merged PR already addresses this — stop |
ready | Ready to proceed |
Agentic Optimizations
| Context | Command |
|---|---|
| Full preflight (default) | bash "${CLAUDE_SKILL_DIR}/scripts/preflight.sh" --project-dir "$(pwd)" |
| Preflight for an issue | bash "${CLAUDE_SKILL_DIR}/scripts/preflight.sh" --issue N |
| Offline / no network | bash "${CLAUDE_SKILL_DIR}/scripts/preflight.sh" --no-fetch |
| Override base ref | bash "${CLAUDE_SKILL_DIR}/scripts/preflight.sh" --base origin/develop |
The script wraps git fetch --prune, git rev-list --left-right --count,
git merge-tree --write-tree, git stash list, and the gh existing-work
lookups behind one structured-output call. See
scripts/preflight.sh.
Quick Reference
| Flag | Description |
|---|---|
git fetch --prune | Fetch and remove stale remote refs |
git status --porcelain=v2 | Machine-parseable status |
gh pr list --search | Search PRs by content |
gh issue view --json | Structured issue data |
git merge-tree | Dry-run merge conflict detection |
git log A..B | Commits in B but not A |