Skip to content

notque/vexjoy-agent / skills/process/pr-workflow

pr-workflow

Flagged

Pull request lifecycle: commit, codex review, sync, review, fix, status, cleanup, and PR mining. Use when user wants to commit changes, get a second-opinion code review from Codex, push changes, create a PR, check PR status, fix review comments, clean up branches after merge, or mine tribal knowledge from PR reviews. Use for "commit my changes", "codex review", "push my changes", "create a PR", "pr status", "fix PR comments", "clean up branches", "mine PRs", or "address feedback".

references/land-pr.md

View on GitHub
# PR Landing Skill

Land an open PR end-to-end: rebase it on a temp branch, run the quality gate, push fork-safe, merge, and verify the merged end state. Use for contributor PRs and any PR that needs a rebase plus local validation before merge.

**End state contract**: `gh pr view` reports state `MERGED`. A `CLOSED` state is a failure — reopen and finish, or report why landing stopped. Final local state: on `main`, fast-forwarded, temp branch deleted.

---

## Instructions

### Step 0: GUARDRAILS

**Goal**: Confirm a safe starting state before touching branches.

```bash
git status -sb   # must be clean
```

Stop and ask the user when any of these hold:

- Working tree has local changes.
- PR is a draft.
- PR has merge conflicts (`mergeable` is `CONFLICTING`).
- Head branch is on a fork and `maintainerCanModify` is false (you cannot push the rebase).

**Gate**: Clean tree, mergeable open PR, push access to the head branch.

### Step 1: CAPTURE PR Context

**Goal**: Record everything needed for the rest of the workflow in one query.

```bash
PR=<number-or-url>
gh pr view "$PR" --json number,title,state,isDraft,mergeable,author,baseRefName,headRefName,headRepository,maintainerCanModify
prnum=$(gh pr view "$PR" --json number --jq .number)
contrib=$(gh pr view "$PR" --json author --jq .author.login)
base=$(gh pr view "$PR" --json baseRefName --jq .baseRefName)
head=$(gh pr view "$PR" --json headRefName --jq .headRefName)
head_repo_url=$(gh api "repos/{owner}/{repo}/pulls/$prnum" --jq .head.repo.clone_url)
```

**Gate**: `state` is `OPEN`; variables captured.

### Step 2: TEMP Branch From Fresh Base

**Goal**: Pin the exact base commit the PR will rebase onto. The temp branch makes the rebase target explicit and keeps `main` untouched until merge.

```bash
git checkout "$base" && git pull --ff-only
git checkout -b "temp/land-pr-$prnum"
```

**Gate**: Temp branch exists at the tip of an up-to-date base.

### Step 3: CHECKOUT PR and Rebase

**Goal**: Replay the PR commits onto the pinned base.

```bash
gh pr checkout "$PR"
git rebase "temp/land-pr-$prnum"
```

Resolve conflicts only when the resolution is obvious from the diff; otherwise `git rebase --abort` and ask the user.

**Gate**: Rebase completes; PR branch now sits on the current base tip.

### Step 4: FIX, Test, Changelog Credit

**Goal**: Make the branch merge-ready with tight scope.

- Apply only fixes needed to land; keep scope to the PR's intent.
- Add or adjust tests when the fix warrants a regression test.
- When the repo keeps a `CHANGELOG.md`, add an entry crediting the contributor: include `#$prnum` and `thanks @$contrib`.

**Gate**: Changes complete, contributor credited.

### Step 5: QUALITY Gate Before Commit

**Goal**: Prove the rebased branch passes the full repo gate locally.

For this repo: `ruff check . --config pyproject.toml && ruff format --check . --config pyproject.toml` plus the test suite. For other repos, run their documented gate (lint, typecheck, tests, docs build).

**Gate**: Every gate command exits 0.

### Step 6: COMMIT Scoped Files

**Goal**: Commit fixes with explicit pathspecs (staging rules: `commit-staging-rules.md`).

```bash
git add <changed-file> [<changed-file>...]   # named paths only
git commit -m "fix: <summary> (#$prnum) (thanks @$contrib)"
land_sha=$(git rev-parse HEAD)
```

Skip this step when Step 4 changed nothing.

**Gate**: Tree clean; `land_sha` recorded.

### Step 7: PUSH Fork-Safe

**Goal**: Update the PR head branch — which may live on a fork — while protecting work pushed since checkout.

A dedicated `prhead` remote targets the head repo directly, so the push works whether the PR comes from a fork or a same-repo branch. `--force-with-lease` rejects the push if the remote moved, protecting contributor commits you have not seen:

```bash
git remote add prhead "$head_repo_url" 2>/dev/null || git remote set-url prhead "$head_repo_url"
git fetch prhead "$head"   # create the tracking ref so the lease has a real baseline
git push --force-with-lease prhead "HEAD:$head"
```

If the lease fails, fetch, inspect the new commits, and redo from Step 3.

**Gate**: Push accepted; PR on GitHub shows the rebased commits.

### Step 8: MERGE

**Goal**: Merge the PR through GitHub so the PR record stays intact.

```bash
gh pr merge "$PR" --squash    # or --rebase per repo convention
```

Merge only — `gh pr close` discards the contribution and breaks the MERGED end-state contract.

**Gate**: Merge command succeeds.

### Step 9: VERIFY End State

**Goal**: Prove the contract, comment with evidence, return local state to clean `main`.

```bash
gh pr view "$PR" --json state,mergedAt --jq '.state + " @ " + .mergedAt'
```

Output must show `MERGED`. Then comment with SHAs and thanks — write the body to a temp file with a quoted heredoc and pass `--body-file` (inline `--body` with `$`/backticks gets shell-mangled):

```bash
merge_sha=$(gh pr view "$PR" --json mergeCommit --jq '.mergeCommit.oid')
cat > /tmp/land-comment.md <<'EOF'
Landed via temp-branch rebase onto BASE.

- Gate: GATE_CMDS
- Land commit: LAND_SHA
- Merge commit: MERGE_SHA

Thanks @CONTRIB!
EOF
# fill placeholders, then:
gh pr comment "$PR" --body-file /tmp/land-comment.md
```

Finally, clean return to main:

```bash
git checkout main && git pull --ff-only
git branch -D "temp/land-pr-$prnum"
git remote remove prhead
git branch --show-current   # must print: main
```

**Gate**: State `MERGED`, comment posted, on `main` at remote tip, temp branch and `prhead` remote removed.

---

## Error Handling

### Error: Rebase conflicts
Cause: Base moved past the PR in conflicting files.
Solution: Resolve only obvious conflicts; otherwise `git rebase --abort`, report the conflicting files, and ask the user.

### Error: `--force-with-lease` rejected
Cause: Contributor pushed new commits after your checkout.
Solution: `git fetch prhead`, review the new commits, redo from Step 3 with them included.

### Error: Push to fork denied
Cause: `maintainerCanModify` is false on the fork PR.
Solution: Ask the contributor to enable "Allow edits by maintainers", or post the rebased diff as review feedback instead of pushing.

### Error: Merge blocked by required checks
Cause: CI has not finished or failed on the rebased head.
Solution: Wait for CI (see `ci-check.md`); if checks fail, fix from Step 4 — leave the PR open, never close it.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall