PR skill: Add fork sync detection and guidance for out-of-sync forks

[ambient-code]

Problem

The /pr skill can fail when a user's fork is out of sync with upstream, particularly when upstream has added workflow files that don't exist in the fork. This results in confusing GitHub API errors about missing workflows permission.

Example Error

refusing to allow a GitHub App to create or update workflow `.github/workflows/amber-auto-review.yml` without `workflows` permission

This error occurs even when:

• The commit being pushed doesn't modify workflow files
• The GitHub App has appropriate permissions
• The user has authorized the app

Root Cause

When a fork is out of sync with upstream and missing workflow files that exist in upstream:

1. A feature branch based on local main (synced with upstream) includes workflow files in its git tree
2. Pushing to the fork would "create" these workflow files (from fork's perspective)
3. GitHub requires workflows permission to create/update workflow files, even via GitHub App
4. The GitHub App typically doesn't have this permission (by design)

Detection Strategy

The PR skill should detect this situation before attempting to push:

# 1. Fetch the fork
git fetch fork

# 2. Check if fork is behind upstream on workflow files
git diff fork/main..main -- .github/workflows/ --name-only

# 3. If differences exist, the fork needs syncing

Recommended Solution

When fork sync is detected as needed:

1. Attempt automated sync (may fail due to workflow permission):

   gh api --method POST repos/FORK_OWNER/REPO/merge-upstream -f branch=main

2. If automated sync fails, provide clear guidance to the user:

   Your fork is out of sync with upstream and contains workflow file differences.
   This requires syncing your fork before I can push.
   
   Please sync your fork by visiting:
   https://github.com/FORK_OWNER/REPO/sync
   
   Or run: gh repo sync FORK_OWNER/REPO --branch main
   (Note: This may require running `gh auth refresh -s workflow` first)
   
   Let me know when the sync is complete and I'll continue with the PR.
   

3. After user confirms sync, rebase the feature branch:

   git fetch fork
   git rebase fork/main BRANCH_NAME
   git push -u fork BRANCH_NAME

Skill Updates Needed

Add a new section to /pr skill after Step 1 (Pre-flight checks):

Step 1f: Check Fork Sync Status

# Fetch fork to get current state
git fetch fork

# Check for workflow file differences
WORKFLOW_DIFF=$(git diff fork/main..main -- .github/workflows/ --name-only)

if [ -n "$WORKFLOW_DIFF" ]; then
  echo "Fork is out of sync with upstream (workflow files differ)"
  # Attempt automated sync or guide user
fi

Additional Considerations

1. Detect other out-of-sync scenarios: Not just workflow files, but significant divergence
2. Cache fork sync status: To avoid repeated fetches in the same session
3. Document the GitHub App limitation: Explain why workflow permission isn't typically granted
4. Improve error messages: When seeing the "refusing to allow" error, immediately recognize it as a sync issue

References

• Session where this was discovered: Context7 MCP permissions PR
• Related GitHub docs: https://docs.github.com/rest/branches/branches#sync-a-fork-branch-with-the-upstream-repository
• Claude Code permissions docs: https://code.claude.com/docs/en/permissions

Success Criteria

• PR skill detects out-of-sync forks before attempting push
• Clear user guidance when manual sync is required
• Automated sync attempted when possible
• Feature branch automatically rebased after fork sync
• Error messages clearly identify fork sync as the issue