Create Pr

Create Pull Request

Opens a GitHub pull request for the current branch with a structured description that maps implementation changes to acceptance criteria, links the originating issue, and requests reviewers. It is a pure consumer of visual proof: it reads the manifest written by [/validate-implementation](../validate-implementation/SKILL.md) and embeds any captured asset inline so reviewers see proof the moment the PR opens. It does not capture recordings itself; recording happens at human-review time, before the PR exists.

Prerequisites

• Apply the shared SDLC conventions in skills/sdlc/references/shared.md.
• If no argument is provided, use $REPO and link $ISSUE_NUMBER.
• gh CLI authenticated with write access to the target repository
• Current branch has commits not on the base branch
• A related GitHub issue number (strongly recommended; omit only for housekeeping PRs)
• Tests passing locally before the PR is opened
• For visual proof (captured beforehand): run [/validate-implementation](../validate-implementation/SKILL.md) on the branch first. It records a CLI demo (via [/record-asciinema](../record-asciinema/SKILL.md)) or a web screenshot (via [/record-playwright](../record-playwright/SKILL.md)) and writes $PROOF_DIR/captured-proof.json. If that manifest is absent, create-pr omits the Visual proof section and suggests running /validate-implementation first (it never captures on its own).

> Note: This skill uses gh (GitHub CLI) directly. For a Graphite-based workflow that diffs against the Graphite parent branch, use /create-pr-description instead.

Skill attribution (GitHub)

Before creating the PR with gh pr create, read [github-post-attribution/SKILL.md](../github-post-attribution/SKILL.md) and append the Created with footer for SKILL_DIR = create-pr to the PR body.

Workflow

Verify branch has commits + tests pass
            |
            v
Compute diff (base..HEAD)
            |
            v
Issue provided? ($1 $2)
   /              \
 Yes               No
  |                 |
  v                 v
Fetch issue       Skip AC
+ map ACs         coverage
  |                 |
  +--------+--------+
           |
           v
Pre-captured proof? ($PROOF_DIR/captured-proof.json)
   /              \
 Yes               No
  |                 |
  v                 v
Read manifest   Before-only state? (proof-manifest.txt
(mode + assets)  exists, captured-proof.json absent)
  |                 /          \
  |               Yes           No
  |                |            |
  |                v            v
  |          Embed before      Omit Visual proof;
  |          alone, note       suggest /validate-
  |          after pending     implementation first
  |                |            |
  +--------+-------+------------+
           |
           v
Embed proof in description (single, or before/after pair)
           |
           v
Upload resolved assets to branch
           |
           v
gh pr create (draft if incomplete)
           |
           v
Assign reviewers (if known)

Steps

1. Confirm the branch has commits ahead of the base:

`` git log origin/$(git rev-parse --abbrev-ref --symbolic-full-name @{u} 2>/dev/null | sed 's|origin/||')..HEAD --oneline `` If no commits, stop and inform the user.

1. Confirm tests pass before opening:

Run the project's test command. If tests fail, stop and list the failures.

1. Compute the diff against the base branch:

`` git diff $(git merge-base HEAD origin/main)..HEAD ``

1. If $1 (repository) and $2 (issue number) are provided, fetch the issue:

`` ghx issue view $2 --repo $1 `` Map each acceptance criterion to the changes in the diff. Note any ACs not yet addressed (to call out in the description).

1. Resolve the visual proof to embed. create-pr consumes proof captured beforehand by [/validate-implementation](../validate-implementation/SKILL.md); it does not capture recordings itself. Resolve the proof directory and detect what is available:

``bash REPO="${1:-$REPO}" ISSUE_NUMBER="${2:-$ISSUE_NUMBER}" PROOF_DIR="/tmp/$REPO/${ISSUE_NUMBER:-housekeeping}" # /tmp/// ``

Authoritative source — captured-proof.json (written by /validate-implementation):

``bash test -f "$PROOF_DIR/captured-proof.json" ``

If present, read it. It is authoritative for which assets to embed:

``json { "captured_at": "", "surface": "cli" | "web" | "none", "mode": "single" | "bugfix-pair" | "bugfix-before-only", "assets": ["pr-demo.gif"] | ["before-bug.gif", "after-fix.gif"] } ``

Embed exactly the files listed in assets (resolved against $PROOF_DIR), in listed order. Render Before / After layout when mode is bugfix-pair (or bugfix-before-only, embedding just the before with a note that after is pending via /validate-implementation). Render the single-asset block when mode is single.

Partial state — before only, no manifest yet: If captured-proof.json is absent but $PROOF_DIR/proof-manifest.txt exists (reproduce-issue captured a before, but /validate-implementation has not yet produced the after), embed the existing $PROOF_DIR/before-bug.* alone with a note that the after recording is pending, and suggest running /validate-implementation to complete the pair.

No proof captured: If neither manifest exists, omit the Visual proof section entirely and note in the PR description (or in console output before creation) that /validate-implementation can capture proof. Do not attempt to capture here.

This is a representative proof, not a claim-by-claim demonstration (that is /validate-pr's job).

1. Upload the resolved asset(s) (from step 5) to the branch and note their raw URLs for the description. Upload only the assets chosen in step 5, not everything in $PROOF_DIR:

`` for asset in "$PROOF_DIR"/; do [ -f "$asset" ] || continue gh api repos/$1/contents/.create-pr-proof/$(basename "$asset") \ --method PUT \ -f message="Add visual proof" \ -f content="$(base64 -w 0 "$asset")" \ -f branch="$(git rev-parse --abbrev-ref HEAD)" done ` When captured-proof.json is the source, iterate its assets list rather than a glob, so unrelated files in $PROOF_DIR are not uploaded. Omit --repo if the repository can be inferred from the current working directory. For each uploaded asset, derive its raw URL as https://raw.githubusercontent.com/$1//.create-pr-proof/`.

1. Draft the PR description following the output format below, embedding the proof if one was captured. Do not line wrap the description; each paragraph/bullet should be a single long line.

1. Create the PR. Use --draft if any acceptance criteria are unmet:

`` gh pr create --repo $1 --title "" --body "$(cat EOF )" [--draft] ` Omit --repo` if the repository can be inferred from the current working directory.

1. If reviewer GitHub handles are known from context, assign them:

`` gh pr edit --add-reviewer ``

PR Description Format

# What

# Why

# How to test

1. 
2. 

# Visual proof

*Captured beforehand by `/validate-implementation`. Run `/validate-pr` for claim-by-claim validation. Omit this section entirely if no proof was captured.*

For a bug fix with a paired before/after recording, use the Before / After layout instead of the single-asset block above:

```markdown
# Visual proof

**Before (bug reproduces):**

**After (fixed):**

*Before captured by `/reproduce-issue`; after captured by `/validate-implementation`. Run `/validate-pr` for claim-by-claim validation.*

If only the before asset exists (after not yet captured), keep the Before block and note that the after will be added once /validate-implementation is run. Omit the section entirely if no proof was captured.

Acceptance criteria coverage

• [x]
• [x]
• [ ]

References

• Closes #

---

Created with [create-pr]({SKILLFILEURL}) (SKILL_SHORT_SHA)

Resolve `SKILL_FILE_URL` and `SKILL_SHORT_SHA` per [`github-post-attribution/SKILL.md`](../github-post-attribution/SKILL.md).

Use `Closes #N` to auto-close the issue on merge. Use `Related to #N` if the PR only partially addresses the issue.

## Example Usage

**Scenario 1: Feature PR linked to an issue**

/create-pr owner/myrepo 42

Diffs branch, fetches issue #42, maps all 4 ACs to changes, creates PR with "Closes #42" and requests reviewers.

**Scenario 2: PR covering only part of an issue**

/create-pr owner/myrepo 88

Issue has 5 ACs; this branch addresses 3. Creates a ready-for-review PR, marks the 2 unmet ACs as unchecked with a note, uses "Related to #88".

**Scenario 3: Housekeeping PR without an issue**

/create-pr

No issue provided. Creates PR with What/Why/How-to-test sections; omits AC coverage and References sections.

**Scenario 4: Incomplete implementation**

/create-pr owner/myrepo 100

One AC not yet met. Opens as a draft PR so it is not accidentally merged.

**Scenario 5: Web UI PR with embedded visual proof**

/create-pr owner/myrepo 130

`/validate-implementation` was run first and wrote `/tmp///130/captured-proof.json` listing `pr-demo-1280x720.png`. `create-pr` reads the manifest, uploads that PNG to `.create-pr-proof/`, and embeds it in a "Visual proof" section so reviewers see the change immediately. It does not start the dev server or capture anything itself.

**Scenario 6: PR where no proof was captured**

/create-pr owner/myrepo 130

No `$PROOF_DIR/captured-proof.json` exists (the user skipped `/validate-implementation`). `create-pr` omits the "Visual proof" section and notes that `/validate-implementation` can capture proof first. The PR opens with the standard sections.

**Scenario 7: Bug-fix PR with paired before/after recordings**

/create-pr owner/myrepo 42

Branch is `fix/42-null-pointer-login`. `/validate-implementation` was run after the fix: it found `/tmp///42/proof-manifest.txt` (written earlier by `/reproduce-issue`, `surface: cli`), replayed that command on the fixed code into `after-fix.gif`, and wrote `captured-proof.json` with `mode: bugfix-pair` listing both `before-bug.gif` and `after-fix.gif`. `create-pr` reads the manifest, uploads both to `.create-pr-proof/`, and renders a Before / After section in the PR body so reviewers see the bug and the fix side by side.

## Completion Checklist

Before requesting review, confirm:

- [ ] Issue linked (Closes vs Related to #N) with acceptance criteria mapped to coverage checkboxes
- [ ] Visual proof embedded if `/validate-implementation` captured it, the section omitted entirely if not (no placeholder left)

Self-check the PR against the [`review-pr` checklist](../review-pr/SKILL.md) and fix what you can, so review finds less to flag.

## Next Step

After the PR is open, use `/handle-pr-ci` if CI is failing, `/handle-pr-feedback` to address reviewer comments, and `/merge-pr` once CI is green and the PR is approved.
Run `/validate-pr` for claim-by-claim runtime validation with per-claim recordings (the proof embedded here is a single representative asset captured by `/validate-implementation`).
Close the loop with `/create-learnings` after the feature is merged.

## Useful Commands Reference

| Command | Description |
|---|---|
| `git log origin/..HEAD --oneline` | List commits ahead of the base branch |
| `git diff $(git merge-base HEAD origin/main)..HEAD` | Diff against the merge base |
| `ghx issue view  --repo ` | Fetch issue details (cached) |
| `gh pr create --repo  --title "..." --body "..." [--draft]` | Open the pull request |
| `gh pr edit  --add-reviewer ` | Assign a reviewer after creation |
| `gh api repos//contents/ --method PUT -f content="$(base64 -w 0 )"` | Upload a visual-proof asset to the branch |

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [tomzx](https://github.com/tomzx)
- **Source:** [tomzx/agents](https://github.com/tomzx/agents)
- **License:** MIT

Install and usage instructions live in the source repository linked above.