/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/nullStep 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/nullIf 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/nullReport:
- 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 -20Step 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 |