/wp-github-flow

name: wp-github-flow
description: "Use when shipping work through GitHub — fixing a GitHub issue by URL/number, or committing and PR-ing uncommitted working-tree changes. Covers resolving ISSUE_REPO vs CODE_REPO, grouping changes into scoped conventional commits (type(scope): summary), branching from fresh origin/base, discovering labels via gh label list, opening PRs with gh pr create, cross-repo Closes footer, merging with --merge (never --squash), and re-syncing after merge. Triggers: \"commit my changes\", \"commit scope by scope\", \"create a branch and PR\", \"open a PR for these changes\", \"fix issue #NNN\", \"debug this GitHub issue\", \"group my changes into commits\", \"push and open a PR\", \"what branch should I use\", \"conventional commit for this change\", \"close this issue with a PR\", \"write a PR description\", \"gh pr create\", \"gh issue view\", \"Closes footer\", \"branch name for this fix\", \"gh label list\", \"bugfix branch\", \"cross-repo close\", \"ISSUE_REPO vs CODE_REPO\", \"stale remote origin\", \"PR body template\", \"merge the open PR\", \"re-sync after merge\", \"sequential PRs\". Not for: plugin version releases — use `wp-plugin-release`; WP.org SVN — use `wp-org-submission`."

GitHub Contribution Flow

> **Model note:** Issue-driven mode (root-cause tracing + fix) requires `sonnet` or `opus`. Changes-driven mode (group + commit existing edits) is mechanical and works well on `haiku`.

Overview

Two entry modes that converge on the same shipping flow (branch → scoped commits → push → PR):

• **Issue-driven** — fetch issue → trace root cause → fix → ship. Wraps `superpowers:systematic-debugging`. Root cause MUST be confirmed before any fix is written.
• **Changes-driven** — read the working tree → group changes by conventional-commit scope → one commit per scope → ship. No issue required.

Both end at **§6 Branch, Commit, PR**, which is shared.

When to use

**Issue-driven:**

• User says "analyze/debug/fix/investigate issue #NNN"
• User pastes a GitHub issue URL and asks to debug it
• User says "find the root cause of this bug" with an issue reference

**Changes-driven:**

• "commit my changes", "commit these scope by scope", "commit by scope"
• "create a branch and PR", "open a PR for these changes"
• "read all changes from X and commit + create PR"
• Any request whose end goal is commits/branch/PR from existing working-tree edits

**Not for:** Plugin version releases or WP.org SVN deploy — use `wp-plugin-release` and `wp-org-submission`. QA failure triage on an already-open PR — use `wp-ci-qa`.

Required Sub-Skill

**Issue-driven only:** Invoke `superpowers:systematic-debugging` before any fix. Do NOT skip Phase 1 (root cause investigation). Changes-driven mode skips this — the edits already exist.

References

• `references/gh-reference.md` — `gh` CLI commands, branch naming rules, label discovery, PR template sections, common CI failures
• `references/project-entry-points.md` — project layout template: repos, plugin dirs, entry-point files, and key conventions; copy and fill in for your project
• `references/conventional-commits.md` — type/scope table, WP-specific scope list, summary rules, multi-commit PR rules, footer conventions, rebase reword

Repo ≠ where the issue lives

The repo that **hosts the issue** is often NOT the repo that **holds the code / receives the PR**. Resolve two names up front and keep them distinct:

• `ISSUE_REPO` — where `gh issue view` / `gh issue edit` run.
• `CODE_REPO` — where the affected code lives; where you branch, push, and `gh pr create --repo "$CODE_REPO"`.

When they differ, the PR's close footer must be **cross-repo**: `Closes ISSUE_OWNER/ISSUE_REPO#N` (a bare `Closes #N` only closes an issue in the same repo).

Real example: issues live in `my-org/my-plugin`, but the buggy code + PR live in `my-org/my-plugin-pro` → PR opens on `my-plugin-pro`, body says `Closes my-org/my-plugin#247`.

---

Changes-Driven Workflow

Use this when the user wants to ship existing uncommitted edits. Skip to §6's mechanics but commit **scope by scope** rather than one lump.

A. Read every change

git status
git diff           # unstaged
git diff --staged  # staged

Read the **full diff**, not just the file list — a single file can contain edits belonging to different scopes, and the commit message's "why" depends on what actually changed.

B. Group changes by scope

Map each change to one conventional-commit scope. **Scopes are project-defined — read the repo's CLAUDE.md for the list, don't assume.**

• ShopFlow: `api, cart, checkout, orders, products, customers, payments, shipping, taxes, coupons, inventory, admin, dashboard, blocks, spa, database, templates, email, reports, build, i18n`.

Group by **what the change is about**, not just which directory it lives in. Examples from real sessions:

• `pages/Coupons/index.jsx` + `pages/Coupons/CouponList/index.jsx` → both `coupons`
• `pages/AbandonedCart/index.jsx`, `pages/Transactions/...` → `admin`
• `.yarnrc.yml`, `package.json` → `build`

One scope can span multiple files; one file *can* split across commits via `git add -p` if it genuinely mixes concerns (rare — prefer not to).

**Exception — one cohesive cross-cutting task = one commit.** Scope-by-scope is the default, but when the change is a *single logical task* that inherently touches many files across categories (e.g. fixing all findings from an audit, a mechanical rename, a dir restructure), a single commit with an **enumerated body** is cleaner and more honest than forcing fragile per-file `git add -p` splits. Judge by intent: distinct concerns → separate commits; one purpose expressed across many files → one commit.

C. Branch first, then commit each scope

Create the branch (§6.1), then make **one commit per scope** so each is independently reviewable and revertable:

git add <files-for-scope-1>
git commit -m "fix(coupons): <imperative summary>"

git add <files-for