github-sync-pr-flow

name	github-sync-pr-flow
description	Use when preparing iPolloWork local changes for GitHub: stash or preserve local edits, sync the current personal branch with remote main, re-apply local work, diagnose conflicts, commit in English, push to the current remote branch, and open a PR to main without creating extra branches.

GitHub Sync, Pull, and PR Flow

Use this workflow for iPolloWork developer submissions, personal-branch syncs, and PR requests. Keep the developer on their current personal branch unless the user explicitly asks for another branch.

Permission Boundary

• This skill is a workflow guide. Do not run the publish flow just because the skill exists.
• Before changing branch history, syncing from main, committing, pushing, creating a PR, or calling GitHub APIs, get explicit user approval for that phase.
• If the user only asks to prepare or document the workflow, only create or update this skill file.
• If the user asks to check readiness, inspect and report state without changing Git state unless they approve the next step.
• If any command would overwrite, drop, rebase, force-push, or otherwise risk local work, stop and ask for explicit approval.

Branch Rules

• Do not create extra branches by default.
• Never commit directly to main.
• Treat the current non-main branch as the developer's personal remote branch.
• Commit messages, PR titles, and PR bodies must be in English.
• Push to the current branch's upstream or origin/<current-branch>.
• PR target is the remote default branch, normally origin/main.

Intent Routing

Choose the smallest workflow that matches the user's words.

• "Submit/commit my code" means commit current local changes and push them to the current personal remote branch. Do not open a PR unless requested.
• "Push my code" means push committed or newly committed changes to the current personal remote branch. Do not open a PR unless requested.
• "Pull/sync/update from main" means preserve local work, bring origin/main into the current personal branch, then restore local work. Do not commit or push unless requested.
• "Open a PR" means ensure the personal branch is pushed, then create a PR from the current branch to main.
• "Merge my code into main" means use the PR flow. Do not push directly to main.
• "Merge the PR" means merge through GitHub after checks and review approval, using the repository's normal merge method.
• Ambiguous requests must be clarified before write operations.

Preflight Check

Before any sync, commit, push, or PR action:

1. Inspect state.
   • Run git status --short --branch, git branch -vv, and git remote -v.
   • Identify current branch, upstream branch, default branch, and dirty files.
   • If on main, stop and ask for the intended personal branch.
2. Inspect scope.
   • Review changed file names and enough diff context to understand what will be affected.
   • If unrelated changes are mixed together, ask which files belong to this operation.
   • Do not stage secrets, .env files, local logs, build artifacts, or generated cache files unless explicitly intended.
3. Confirm the next phase.
   • State which workflow will run: pull/sync only, commit/push only, PR only, or PR merge.
   • Continue only after the user approves that phase.

Pull / Sync From Main

Use this when the user asks to pull, sync, update from main, or prepare their personal branch before submission.

1. Start from the current personal branch.
   • Confirm the branch is not main.
   • Confirm the remote target is origin/main.
2. Preserve local work.
   • If the worktree is dirty, run git stash push -u -m "<clear English message>".
   • Record the stash ref and summary.
   • If git stash fails, stop and report the error.
3. Fetch remote state.
   • Run git fetch origin --prune.
   • Do not use plain git pull for this workflow because it hides whether the incoming changes came from main, the current branch upstream, or both.
4. Merge remote main into the current personal branch.
   • Run git merge origin/main unless the repository explicitly documents a rebase workflow.
   • If the merge conflicts, stop immediately.
   • Report conflict files, modules, remote/main changes, and local branch changes.
   • Ask the user how to resolve before editing conflict hunks.
5. Re-apply local work.
   • Run git stash pop for the saved stash.
   • If stash pop conflicts, stop immediately.
   • Report conflict files, modules, remote/main changes, and local stashed changes.
   • Keep the stash until the restored changes are confirmed safe.
6. Validate local state.
   • Run git status --short --branch.
   • Run git diff --check.
   • Run narrow checks only if the user approved validation or the next workflow depends on it.
7. Stop.
   • Do not commit, push, or open a PR after pull/sync unless the user explicitly asks.

Commit And Push To Personal Branch

Use this when the user says "submit my code", "commit my code", or "push my code" without asking to merge to main.

1. Run the preflight check.
2. Confirm intended files.
   • Stage only the files that belong to the user's request.
   • Avoid git add -A when unrelated changes exist.
3. Validate.
   • Run git diff --check.
   • Run relevant tests, typecheck, or lint for changed areas when available.
4. Commit.
   • Use a concise English commit message.
   • Mention the feature, fix, or workflow changed.
5. Push.
   • Run git push -u origin <current-branch>.
6. Stop.
   • Do not open a PR unless the user requested it.

PR To Main

Use this when the user asks to open a PR or merge their code toward main.

1. Run the pull/sync workflow first unless the user explicitly says the branch is already synced.
2. If new local changes remain after sync, run the commit and push workflow.
3. Open PR.
   • Prefer GitHub CLI or GitHub API, depending on local availability.
   • Base branch: main.
   • Head branch: current personal branch.
   • Title/body in English.
   • Body should describe what changed, why, validation, and known risks.
4. Stop after PR creation unless the user explicitly asks to merge the PR.

Merge PR Into Main

Use this only when the user explicitly asks to merge into main.

1. Confirm the PR target is main and the head branch is the user's personal branch.
2. Check required CI status and review state.
3. If checks or review are missing, report what is blocking merge.
4. If merge conflicts exist on GitHub, report the conflict modules and ask how to proceed.
5. Merge through GitHub using the repository's normal merge method.
6. Do not push directly to main from local unless the repository owner explicitly requires it.

Conflict Report Format

When conflicts occur, report:

• Conflict file path.
• Module or feature area.
• Remote/main side: concise description from git diff --ours or upstream context.
• Local side: concise description from git diff --theirs, stash context, or working-tree context.
• Same area changed by whom when known from commit authors.
• Recommended resolution when it is clear.
• Required decision: keep remote, keep local, or combine.

Do not resolve conflicts without user confirmation unless the resolution is mechanically obvious and explicitly allowed.

Legacy Full Submission Flow

Use this only when the user explicitly asks for the full sequence from local changes to PR.

1. Inspect state and confirm scope.
2. Stash dirty local edits.
3. Fetch/prune origin.
4. Merge origin/main into the current branch.
5. Pop stash.
6. If conflicts occur, stop and ask.
7. Validate locally.
8. Stage intended changes.
9. Commit in English.
10. Push to origin/<current-branch>.
11. Open PR to origin/main.
12. Summarize PR URL, commit hash, checks, and remaining risks.