push

name	push
description	Push current branch changes to origin and create or update the corresponding pull request; use when asked to push, publish updates, or create pull request.

Push

Prerequisites

• gh CLI is installed and available in PATH.
• gh auth status succeeds for GitHub operations in this repo.

Goals

• Push current branch changes to origin safely.
• Create a PR if none exists for the branch, otherwise update the existing PR.
• Keep branch history clean when remote has moved.

Related Skills

• pull: use this when push is rejected or sync is not clean (non-fast-forward, merge conflict risk, or stale branch).

Steps

1. Identify current branch and confirm remote state.

2. Run local validation (npm test, npm run build, npm run check:meta) before pushing.

3. Push branch to origin with upstream tracking if needed, using whatever remote URL is already configured.

4. If push is not clean/rejected:

   • If the failure is a non-fast-forward or sync problem, run the pull skill to merge origin/main, resolve conflicts, and rerun validation.
   • Push again; use --force-with-lease only when history was rewritten.
   • If the failure is due to auth, permissions, or workflow restrictions on the configured remote, stop and surface the exact error instead of rewriting remotes or switching protocols as a workaround.

5. Ensure a PR exists for the branch:

   • If no PR exists, create one.
   • If a PR exists and is open, update it.
   • If branch is tied to a closed/merged PR, create a new branch + PR.
   • Write a proper PR title that clearly describes the change outcome
   • For branch updates, explicitly reconsider whether current PR title still matches the latest scope; update it if it no longer does.

6. Write/update PR body with a clear structure:

   • Summary: what changed and why.
   • Spec Alignment: relevant SPEC.md sections.
   • Verification: exact commands run and outcomes.
   • If PR already exists, refresh body so it reflects total branch scope (not just newest commits).

7. If a PR template exists in the target repo, follow it exactly. Otherwise use the structured body above and ensure governance checks pass.

8. Submit/update through the governed wrapper (mandatory):

   • npm run submit:pr-governed -- --mode create --title "<clear PR title written for this change>"
   • npm run submit:pr-governed -- --mode edit
   • Wrapper sequence is deterministic and mandatory: normalize body -> check:pr-governance -> check:meta -> gh pr create/edit --body-file <normalized-file>.

9. If body/review text references output/playwright/*, replace the local path reference with the Linear issue evidence comment created by the linear-ui-evidence skill before wrapper submit.

10. Reply with the PR URL from gh pr view.

Commands

# Identify branch
branch=$(git branch --show-current)

# Validation gate
npm test
npm run build
npm run check:meta

# Initial push: respect the current origin remote.
git push -u origin HEAD

# If that failed because the remote moved, use the pull skill. After
# pull-skill resolution and re-validation, retry the normal push:
git push -u origin HEAD

# If the configured remote rejects the push for auth, permissions, or workflow
# restrictions, stop and surface the exact error.

# Only if history was rewritten locally:
git push --force-with-lease origin HEAD

# Ensure a PR exists (create only if missing)
pr_state=$(gh pr view --json state -q .state 2>/dev/null || true)
if [ "$pr_state" = "MERGED" ] || [ "$pr_state" = "CLOSED" ]; then
  echo "Current branch is tied to a closed PR; create a new branch + PR." >&2
  exit 1
fi

# Write a clear, human-friendly title that summarizes the shipped change.
pr_title="<clear PR title written for this change>"

# Write/edit PR body to include Summary, Spec Alignment, and Verification.
# If this repo has a PR template, follow it; otherwise keep the above sections.
# Ensure governance checks are green before finalizing push/PR.
cat > .git/.symphony-pr-body.md <<'MD'
<full markdown PR body>
MD
if [ -z "$pr_state" ]; then
  npm run submit:pr-governed -- --mode create --title "$pr_title"
else
  # Reconsider title on every branch update; edit if scope shifted.
  npm run submit:pr-governed -- --mode edit
fi

# Show PR URL for the reply
gh pr view --json url -q .url

Notes

• Do not use --force; only use --force-with-lease as the last resort.
• Distinguish sync problems from remote auth/permission problems:
  • Use the pull skill for non-fast-forward or stale-branch issues.
  • Surface auth, permissions, or workflow restrictions directly instead of changing remotes or protocols.