Menu
Open a pull request as a decision package — summary + inline content for review + explicit "things to push back on" + test plan with checkboxes + Closes
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Live decision-review session between graveyard shifts. Compile every decision and approval currently waiting on the user — across ALL prior shifts, not just the latest — walk them together, and RECORD each outcome onto GitHub as shaped permission rather than executing it live (execution is the graveyard's job; building/merging mid-meeting just makes the user wait). Reactions are cues to capture; even approvals are deferred to the next graveyard. End by publishing the report and — with standing permission — launching that graveyard shift.
Adversarially review a graveyard shift's brief BEFORE it's published — kill false gates, sharpen real ones, surface actionable work the shift left behind, and loop the graveyard if real work remains. Use as the closing/looping phase of graveyard-shift, right after the Shift Report is drafted and before it's published to Notion. This is what makes a graveyard shift loop until review finds no actionable-now work remaining; it is NOT run during a shift-change (that's a live meeting with the user and can't loop).
Work through the open issue backlog autonomously. Auto-ship the small clean fixes, prep draft PRs for review on bigger ones, file refined proposals when design choices need user input. For unattended sessions where the user is sleeping / away and wants to wake up to a productive set of changes.
The definition-of-done gate. Run before declaring any unit of work done or finished — before merging an auto-ship, handing back a draft PR, closing an issue, or listing an item as "shipped" in a shift report. Nine ownership questions plus a short close-out posted on the PR/issue. Any unanswerable question flips the item to a lesser bucket instead of shipping a hole.
Review a plan, issue, spec, PR, current diff, or implementation against an authoritative source of truth; identify missing, incorrect, risky, overcomplicated, or unverifiable work; patch clear gaps when requested; optionally run an advisory external reviewer (e.g. the codex-pr review loop / codex/AGY) for implementation diffs.
Use when urgency matters and the right move is a direct, root-cause fix instead of cautious layering.
| name | pr-package |
| description | Open a pull request as a decision package — summary + inline content for review + explicit "things to push back on" + test plan with checkboxes + Closes |
Standard shape for pull requests. A good PR isn't a code dump — it's a decision package. The user reviews once; every call you made that they could redirect should be visible.
## Summary
- [1-3 bullets: what changed, why, in 1 sentence each]
[For content-heavy PRs: INLINE the content here for review — JSON schemas, prose excerpts, config snippets. Never link to a sidecar file the user has to bounce to.]
## Things to push back on
- **[Decision 1]:** [the call you made + the alternative you considered + the reason you chose this. Make redirecting cheap.]
- **[Decision 2]:** ...
- **[Decision 3]:** ...
## Scope cap (optional, when the PR could have grown)
- [What this PR deliberately does NOT change]
- [Why that boundary]
## What [user] should look at first
[Optional: 1-3 ordered items. Most useful when the diff is large or content-heavy.]
Closes #[N]
## Test plan
- [x] [Test that ran and passed]
- [x] [Another test that ran and passed]
- [ ] [Test the user needs to run / decision the user needs to make]
- [ ] [codex-pr review round, if code change]
[Draft until the codex-pr review passes + user's eye if his-eye-required.]
"Things to push back on" is REQUIRED on any PR with non-trivial decisions. Don't ship a PR that only describes WHAT changed. Surface the choices you made that the user could reasonably redirect. Each item = the call + the alternative + the why.
INLINE content for review. If the PR adds JSON files, markdown content, prompt text, copy, schema — render the content inline in the PR body. Do not link to a .json or .md file and ask the user to bounce. The PR body IS the rendered view. (See memory: feedback_inline_structured_content.)
Closes #N — every PR references the issue it closes. Squash-merge then auto-closes. If the work doesn't have an issue, file one first (small ≠ disposable, see CLAUDE.md + feedback_github_issues_not_todos).
Test plan with checkboxes. Use - [x] for done, - [ ] for what still needs to happen. Make the gating items obvious.
Clickable file paths when referencing files in the body: [path](file:///abs/path), NOT code-tag spans. (See memory: feedback_clickable_file_links.)
No emojis in the body or commit message body unless the user has explicitly asked.
Co-Authored-By trailer on commit messages:
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Heredoc for commit messages and PR bodies when passed via git commit -m or gh pr create --body to preserve formatting:
git commit -m "$(cat <<'EOF'
subject line
body paragraph with proper wrapping.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
EOF
)"
The PR package is itself a decision bundle. Before opening, decide each of these and surface them as either commits, body content, or "things to push back on":
origin/main, named after the topic (not generic; see feedback_worktree_naming). Branch follows. PR follows. Issue exists first or gets filed.git add . or git add -A. Stage specific files. Discuss what to include with the user before bulk-committing untracked files. (See memory: feedback_selective_commits.)his-eye-required flag.#230 split), CARVE IT — ship the shippable, park the rest in a sibling draft with a clear blocked: label. Don't let parked content hold up shipped value.blocked: voice-pass, blocked: <topic>), update the body with a "Status: PARKED" section explaining what unblocks it, and leave it visibly waiting. Do NOT close it — ideas stay. (See feedback_research_brief_pattern for the related synthesis rule.)feedback_aggressive_overnight_drafts.)# In primary worktree:
gh issue view <N> # confirm the issue exists or create it first
git worktree add -b feat/<topic-name> /Users/ray/Documents/<repo>/.claude/worktrees/<topic-name> origin/main
# Work in the worktree. Selective stage. Commit with heredoc + Co-Authored-By.
gh pr createWrite the body to a heredoc variable or temp file first so you can see the full shape. The body is the artifact — don't compose it inline in a single bash call.
gh pr create --title "<type>(<scope>): <subject>" --body "$(cat <<'EOF'
[full body per the shape above]
EOF
)"
For draft PRs add --draft. For draft PRs with a blocked: reason, also run gh pr edit <N> --add-label "blocked: <reason>".
gh pr ready <N>
gh pr merge <N> --squash --delete-branch
For PRs sitting in worktrees that block local branch deletion, that's a known wrinkle — the remote merge still succeeds, just clean the worktree after.
gh issue view <N> — if not, comment-close manually with a pointer to the merged PR.
Title format: <type>(<scope>): <subject under 70 chars>
Types in use in Ray's repos: feat, fix, docs, chore, refactor, test. Scope is optional but usually matches the area (mentor, rubric, approaches, observability).
Subject in imperative mood, no trailing period.
gh pr create or git commit -m.research-brief skill).decision-package skill).The chat message back to the user should include: