/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 get-url origin
• 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

Step 1: Fetch Latest Remote State

git fetch origin --prune 2>/dev/null

Step 2: Check for Existing Work

If an issue number was provided, check if it's already addressed:

# Check if issue exists and its state
gh issue view $ISSUE --json number,title,state,labels 2>/dev/null

# Check for PRs that reference this issue
gh pr list --search "fixes #$ISSUE OR closes #$ISSUE OR resolves #$ISSUE" --json number,title,state,headRefName 2>/dev/null

# Check for branches that reference this issue
git branch -a --list "*issue-$ISSUE*" --list "*fix/$ISSUE*" --list "*feat/$ISSUE*" 2>/dev/null

If a merged PR exists: Report that the issue is already addressed. Stop. If an open PR exists: Report the PR and ask if the user wants to continue on that branch or start fresh.

Step 3: Verify Branch State

# Check divergence from main/master
git log --oneline origin/main..HEAD 2>/dev/null || git log --oneline origin/master..HEAD 2>/dev/null

# Check if main has moved ahead
git log --oneline HEAD..origin/main -5 2>/dev/null || git log --oneline HEAD..origin/master -5 2>/dev/null

# Check for uncommitted changes
git status --porcelain=v2 --branch 2>/dev/null

Report:

• Commits ahead/behind remote
• Uncommitted changes that might interfere
• Whether a rebase is needed

Step 4: Check for Conflicts

# Dry-run merge to detect conflicts (without actually merging)
git merge-tree $(git merge-base HEAD origin/main) HEAD origin/main 2>/dev/null | head -20

Step 5: Summary Report

Output a structured summary:

Check	Status	Detail
Remote state	fresh/stale	Last fetch time
Existing PRs	none/open/merged	PR numbers if any
Branch state	clean/dirty/diverged	Ahead/behind counts
Conflicts	none/detected	Conflicting files
Stash	empty/N items	Stash contents

Recommendations:

• If behind remote: "Rebase recommended before starting work"
• If existing PR found: "PR #N already addresses this - review before duplicating"
• If dirty state: "Commit or stash changes before branching"
• If conflicts detected: "Resolve conflicts with main before proceeding"
• If clean: "Ready to proceed"

Agentic Optimizations

Context	Command
Quick remote sync	git fetch origin --prune 2>/dev/null
Check existing PRs	gh pr list --search "fixes #N" --json number,state,headRefName
Branch divergence	git log --oneline origin/main..HEAD
Conflict detection	git merge-tree $(git merge-base HEAD origin/main) HEAD origin/main
Compact status	git status --porcelain=v2 --branch
Remote tracking	git branch -vv --format='%(refname:short) %(upstream:track)'

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