git:20260821.878d2e3 to git:20260822.6b82b02

---

name: create-pr

description: Opens a GitHub PR for the current branch linked to the Pocket issue (Pocket Enterprise). User-triggered recorder — commits traveling state, formats a structured PR body, discovers or creates the PR, and records it in .pocket-meta.json. Trigger on "create-pr", "open a PR", "create pull request", or when pocket-development offers it after a phase completes in enterprise mode.

---

# Create PR

Standalone Pocket Enterprise skill. Opens (or reuses) a GitHub pull request on the **current branch** for a completed development phase. Pocket does **not** manage git branches — no checkout, create, or switch.

**Core principle:** Recorder only. The PR is created or discovered; warnings (e.g. >20 files) are surfaced but never block. Enforcement stays with CI and the human supervisor.

**Use this when:** Pocket Enterprise is enabled, phase tasks are DONE on the current branch, and you need the structured PR gate (what / why / how-to-test, issue link via `refs` or `closes`).

**Do NOT use when:** Enterprise mode is off — run `pocketto-pi mode` first; this skill will explain and stop.

---

## Invocation

```text

/pocketto:create-pr <plan_dir> [<phase_file>]

```

Examples:

```text

/pocketto:create-pr docs/pocket/plans/2026-06-09-github-trace-loop/

/pocketto:create-pr docs/pocket/plans/2026-06-09-github-trace-loop/ execution-plan/phase-1.md

```

- `<plan_dir>` — directory containing `log.json` and execution plan file(s).

---

## Hard Constraints

<HARD-GATE>

1. **NO branch management** — never `git checkout`, `git switch`, `git branch`, or `git worktree` for PR creation. PR opens on whatever branch `git rev-parse --abbrev-ref HEAD` returns.

2. **Traveling state BEFORE `gh pr create`** — `git add -f` + commit `log.json`, plan docs, and spec docs first (no-op if nothing to commit).

3. **Always `--body-file`** — never inline multi-line `gh pr create --body "…"` (cross-shell quoting hazard).

4. **Recorder / non-blocking** — `fileWarning` (>20 files) is surfaced to the user; PR creation still proceeds.

</HARD-GATE>

---

## Preflight

Run ALL steps before any git add or `gh` call.

### Step 1: Enterprise mode

```bash

npx -y pocketto-pi mode --json --contract 2

```

Parse the JSON envelope:

- If `ok` is `false` → **STOP.** Explain the mode error and how to fix Pocket Enterprise config.

- If `data.enterprise` is not strictly `true` → **STOP.** Explain that `create-pr` requires Pocket Enterprise (`pocketto-pi mode init` or a `## Pocket Enterprise` heading in `AGENTS.md`). Do not call `gh`.

### Step 2: gh authentication (skill layer)

```bash

gh auth status

```

If not authenticated → **STOP** with an actionable `gh auth login` error. No partial meta write, no commit, no PR.

### Step 3: Resolve paths

| Input | Resolution |

|-------|------------|

| `plan_dir` | Absolute path to the plan directory |

| `spec_dir` | `docs/pocket/spec/<slug>/` where `<slug>` matches the plan directory basename (e.g. `2026-06-09-github-trace-loop`) |

### Step 4: Linked issue

```bash

npx -y pocketto-pi meta get <spec_dir> github_issue.number --json --contract 2

```

If no issue number → **STOP.** Explain that issue creation must run first (pocket-grinding Story 1 handoff). No PR without a linked issue.

---

## Current Branch

```bash

git rev-parse --abbrev-ref HEAD

```

Record as `<branch>`. This is the **only** branch reference used for PR discovery and creation. Do not change branches.

---

## PR Discovery (idempotent — no duplicates)

**Step A — meta:**

```bash

npx -y pocketto-pi meta get <spec_dir> phases.<phase_key>.github_pr.number --json --contract 2

```

If `data.value` is a positive PR number → fetch URL via `meta get … phases.<phase_key>.github_pr.url` (or `gh pr view <N> --json url`) and report reuse. **Stop** — do not create a duplicate.

**Step B — GitHub by branch (recovery when meta write was lost):**

```bash

gh pr list --head <branch> --json number,url

```

If any PR is returned → reuse the first match, record via [Record PR](#record-pr) below, report reuse. **Stop** — do not create a duplicate.

---

## Commit Traveling State (before `gh pr create`)

Enterprise mode requires `log.json` and plan/spec docs on the PR so pocket-development's phase-level pass can compute per-task SHA scope.

```bash

git add -f <plan_dir>/log.json <plan_dir> <spec_dir>

git diff --cached --quiet || git commit -m "chore(pocket): traveling state for <phase_key>"

```

- Use `git add -f` so gitignored paths (e.g. `log.json` under `docs/`) are included.

- If the index is unchanged after `git add`, skip commit (no-op).

- Push is **not** required by this skill — the recorder commits locally; the user or CI may push. If `gh pr create` needs the branch on the remote, surface that as a prerequisite failure from `gh`, not by branching.

---

## Build PR Body

### Structured input

Write a temp JSON file (Node `fs` — no shell heredocs):

| Field | Source |

|-------|--------|

| `issue` | Issue number from meta (Step 4) |

| `finalPhase` | `true` if this is the **last** phase in `log.json` (or the only phase in a flat plan); `false` for non-final phases in a multi-phase plan |

| `fileCount` | Count of files changed for this phase: `git diff --name-only <phase_baseline>..HEAD` (use `log.json` phase `baseline_sha` or first task's range; dedupe paths) |

| `what` | What this phase delivers — from phase file / task summaries |

| `why` | Why this work — from spec or plan context |

| `howToTest` | Verification steps — from plan acceptance criteria / test commands |

`finalPhase` drives the issue link keyword: `closes #N` (final/sole phase) vs `refs #N` (non-final multi-phase).

### Format and create

```bash

npx -y pocketto-pi format pr --input <pr-input.json> --json --contract 2

```

Parse `data.bodyFile` and `data.fileWarning`.

If `data.fileWarning` is `true` → surface a one-line warning to the user (≤20-file-per-PR rule). **Continue** — non-blocking.

```bash

gh pr create --head <branch> --title "<phase title>" --body-file <data.bodyFile>

```

Derive `--title` from the phase file heading or plan slug. Parse `gh` output for PR number and URL.

---

## Record PR

Only after successful create or reconcile — never before:

```bash

npx -y pocketto-pi meta set <spec_dir> phases.<phase_key>.github_pr.number <N> --json --contract 2

npx -y pocketto-pi meta set <spec_dir> phases.<phase_key>.github_pr.url "<url>" --json --contract 2

```

---

## Completion Report

```

PR_READY: <phase_key>

Branch: <branch>

PR: #<N> <url>

Issue link: <refs|closes> #<issue>

fileWarning: <true|false>

```

If reused (meta or `gh pr list`): report `PR_REUSED` instead of `PR_READY`.

---

## Red Flags

| Thought | Counter |

|---------|---------|

| "I'll create a feature branch first" | **STOP.** This skill never manages branches. PR opens on the current branch. |

| "Skip the traveling-state commit" | **STOP.** Review needs `log.json` + docs on the PR. Commit before `gh pr create`. |

| "23 files — don't open the PR" | Recorder is non-blocking. Warn and create anyway. |

| "I'll inline the PR body" | Always `format pr` → `--body-file`. Deterministic and cross-OS safe. |

| "No issue yet — create PR anyway" | **STOP.** Issue-first is a hard gate. Run pocket-grinding issue creation first. |