gh-pr-publish

What this skill does

# GH PR Publish

Create or update a GitHub pull request from local changes without losing context
or pushing unsafe work.

## Contract

Inputs:

- Repository root
- Current branch, target branch, and optional existing PR number
- Optional user preference: draft or ready PR

Outputs:

- PR URL
- Title/body summary
- Checks run or skipped
- Any remaining approval gates

Creates/Modifies:

- May create a local branch, stage files, create commits, push, and create or
  edit a GitHub PR after approval
- May create a temporary PR body file

External Side Effects:

- Writes git history when committing
- Pushes branches to GitHub
- Creates or edits GitHub pull requests

Confirmation Required:

- Before staging broad/unrelated files
- Before creating a commit
- Before pushing
- Before creating or editing a PR
- Before marking a draft PR ready

Delegates To:

- `commit-summary` to create a Conventional Commit
- `gh-fix-ci` when PR checks fail
- `release-pr-gates` for develop/staging/production promotion PRs
- `gh-project-board` when the PR must be added to a project board

## Workflow

1. Verify GitHub and git context:

   ```bash
   gh auth status -h github.com
   gh repo view --json nameWithOwner,defaultBranchRef,url
   git status -sb
   git branch --show-current
   git remote -v
   ```

2. Protect default branches:
   - If on `main`, `master`, `develop`, or `staging`, create a feature branch
     before committing unless the user explicitly requested a release PR.
   - Use branch prefix `codex/` unless the repo has a stronger convention.
   - Never rewrite shared branch history.

3. Inspect work before writing:

   ```bash
   git diff --stat
   git diff --cached --stat
   git log --oneline --decorate -10
   ```

   If unrelated files are present, list them and get approval before staging.

4. Commit only after approval:

   ```bash
   git add <approved-paths>
   git diff --staged --stat
   git commit -m "<message>"
   ```

5. Build the PR body from evidence:
   - Summary: what changed and why
   - Changes: concise bullets grouped by behavior or subsystem
   - Verification: exact checks run, or `Not run` with reason
   - Risk: migrations, env vars, data changes, rollout notes
   - Follow-ups: only real remaining work

   Preserve useful existing body sections when updating an open PR.

6. Find or create the PR:

   ```bash
   gh pr list --head <branch> --state open --json number,title,url,baseRefName
   gh pr create --base <base> --head <branch> --draft --title "<title>" --body-file <body-file>
   gh pr edit <number> --title "<title>" --body-file <body-file>
   ```

   Default to draft unless the user asked for ready review or the repo convention
   clearly requires ready PRs.

7. Push only after approval:

   ```bash
   git push -u origin <branch>
   ```

8. Report:
   - PR URL
   - Branch and base
   - Draft/ready state
   - Checks run
   - Any required human action

## PR Body Rules

- Use real newlines via `--body-file`; do not pass escaped markdown inline.
- Do not use `--fill` as the final body if the diff needs context.
- Do not claim tests passed unless they were run in this session or clearly
  visible from CI.
- If the PR closes issues, include `Closes #123` only when the issue is truly
  resolved by the PR.
- If there is no meaningful body, write a short one; blank PR bodies rot.