github-sync-pr-flow

# 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 bran