shift-editor/shift / .claude/skills/pr
pr
VerifiedCanonical rules for preparing, opening, and updating Shift pull requests. Use whenever the user asks to create, open, draft, update, or review a pull request. Enforces issue discovery and linkage, Conventional Commit titles, release-note quality, complete validation evidence, and safe pushing.
/pr — How Shift pull requests are written
A pull request is one reviewable product or engineering change. Its title must make sense in history and as potential Release Please input.
Title syntax
Every pull request title uses Conventional Commits:
<type>[optional scope][optional !]: <concise imperative description>
Use the same types and subject rules as /commit. Examples:
feat: add source conversion preview
fix(document): preserve the last valid save
ci: publish signed Alpha artifacts
The title must:
- be at most 72 characters;
- use lowercase imperative wording after the colon;
- describe the user or system outcome, not the list of files changed;
- omit trailing punctuation, emoji, agent labels, and
[codex]prefixes.
CI rejects titles that are not Conventional Commits. GitHub may also use the pull request title as a squash commit subject, so treat it as release-quality history.
Release Please behavior
Release Please reads conventional commits merged to main and maintains a draft release pull request.
feat,fix, andperfbecome public changelog entries.refactor,test,docs,build,ci,style, andchoreremain valid but are hidden from public release notes.- Ordinary pull requests must not bump the product version or edit generated changelog sections.
- Maturity and milestone changes require explicit user approval and a
Release-As:footer. - The generated
chore: release Shift …pull request is special: review its version, changelog, warning text, and artifact readiness before merging it.
Pull request body
Use a concise body with evidence:
## Summary
- what changed and why
- important behavioral or architectural boundary
## Issue
Closes #123
## Testing
- `exact command`
- focused manual verification
Add ## Risks or ## Follow-up only when they materially help review. Do not add empty sections, generic claims such as “tests pass,” generated marketing prose, or agent attribution.
Testing entries must distinguish:
- commands that passed;
- checks that failed and why;
- checks not run;
- focused manual verification where an automated test would be low value.
For release changes, state whether packaging was smoke-tested and which hosted platform/signing checks remain.
UI review evidence
For materially visible UI changes, attach screenshots or recordings before marking the pull request ready for review.
- Cover every distinct state needed to review the change, including native dialogs and fallback, error, empty, loading, or disabled states when affected.
- Capture the actual implementation. Include before-and-after evidence when the change intentionally modifies existing appearance or interaction.
- Prefer GitHub user attachments over committing review-only media to the repository.
- Redact private user data, credentials, and sensitive documents before uploading.
- If useful evidence cannot be captured safely or reliably, state why in the pull request rather than silently omitting it.
Do not add ceremonial screenshots for changes with no visible review surface.
Desktop E2E impact
For changes that can affect desktop user flows or rendering, complete the E2E impact check in apps/desktop/e2e/README.md before opening or updating the pull request.
- Search existing specs by affected surface, command, or workflow even when the branch does not change E2E files.
- Run the smallest relevant Playwright project, file, and title filter. Run the complete affected project for broad or shared-fixture changes.
- Update visual snapshots only for intentional appearance changes, inspect every changed image, and rerun without update mode.
- List exact E2E commands in
## Testing; explicitly identify relevant E2E coverage not run and why.
Issue linkage
Every ordinary pull request includes ## Issue. Search open and recently closed issues before opening or updating the pull request, and reference every issue materially addressed by the change.
- Use
Closes #123only when the pull request fully satisfies that issue's acceptance criteria. Merging to the default branch then closes the issue. - Use
Refs #123for partial work, prerequisites, investigation, or related context. The issue remains open. - If substantial feature, bug, regression, or roadmap work has no adequate issue, invoke
/issueand create one before opening the pull request. - For small maintenance, documentation, dependency, or mechanical work with no issue, write
No issue — <brief reason>rather than creating a ceremonial issue. - Generated Release Please and dependency-bot pull requests are exempt from the issue section.
Never use a closing keyword merely because an issue is related. If any accepted outcome remains, use Refs.
One pull request per end state
Review a change once, as it will stay. When work toward one goal takes several steps, such as a new module, then wiring it in, then deleting what it replaces, put the steps in one pull request rather than a stack of pull requests that each depend on the last.
- Open it as a draft once the first step lands, and keep pushing commits to it until the end state is reached. List what remains in its body as a checklist, then mark it ready.
- Order the commits so the change still reads step by step: each commit builds and passes its tests, and later commits do not rewrite earlier ones without reason.
- Split out anything that stands on its own: a bug fix found along the way, a safety fix, a performance change that helps today. Each gets its own pull request against the default branch, and the long-running branch merges it in rather than waiting for it.
- Stop the pull request at a state worth reviewing as a whole, such as a feature working with its old path deleted. A later phase with a different end state, such as moving authority or adding a new capability, is its own pull request.
- When a stack already exists, fold it: merge the default branch into its tip, open one draft from there, and close the stacked pull requests with a comment pointing at it.
Preparation process
- Read
git status, staged and unstaged diffs, the branch commits, and the complete diff againstmain. - Confirm the branch contains only the requested change. Do not absorb unrelated dirty files.
- Search open and recently closed issues; decide whether the pull request closes, references, or does not require an issue.
- For substantial untracked work, invoke
/issuebefore opening the pull request. - Use
/committo create any required logical commits. - Rebase or merge the current
mainonly when needed. Do not rewrite a published branch without explicit approval. - Run focused validation and the repository checks required by the affected subsystem, and the scanners over the branch (
pnpm scan:ts --since origin/main,pnpm scan:rust --since origin/main; see/add-lint's "Running the scanners on a branch"). Fix each finding the branch introduced or say in the body why it stays. - Re-read the final diff and summarize observable behavior, not implementation trivia.
- Choose a Conventional Commit title that matches the dominant change.
- Push the named branch without force unless explicitly approved.
- Create the pull request with an explicit base and head, preferably using a body file to preserve formatting.
- Verify the rendered issue keyword and all body formatting on GitHub.
- Return the pull request URL, title, issue relationship, commit list, and validation status.
A request to create or update a pull request authorizes the ordinary push needed for that request. It never authorizes force-pushing, changing repository settings, merging the pull request, or publishing a release.
Review process
When reviewing a pull request:
- inspect the diff and tests rather than trusting the body;
- verify the title matches Conventional Commits and the actual dominant change;
- identify user-visible
feat,fix, andperfwording that would be confusing in release notes; - verify the issue section exists, every linked issue is relevant, and
Closesis used only for complete resolution; - check that version and generated changelog edits appear only in a Release Please pull request;
- distinguish blocking correctness issues from optional improvements;
- verify claims against repository behavior and report exact paths and lines.
Hard rules
- Never open an ordinary pull request without searching for relevant issues and including an issue section.
- Never stack pull requests that each depend on the last for one goal; grow one draft to its end state and split out only what stands on its own.
- Never open a pull request from a branch with uncommitted intended changes.
- Never include credentials, signing material,
.envfiles, or tokens. - Pull request titles, bodies, comments, commits, and release-note wording must describe the change and its validation, not the process used to produce it. Never include incidental execution metadata such as agent identity, handoff mechanics, remote hosts, machine names, tmux sessions, worktree paths, or “finishing work off.” Mention such infrastructure only when it is itself the subject of the change. Platform names are allowed only when materially relevant to behavior or testing evidence.
- Never force-push, merge, enable auto-merge, or publish a release unless the user explicitly asks.
- Never fabricate issue links, test results, screenshots, reviewers, or release-note claims.
- Never hide a failed or skipped check from the pull request body.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |