Opening a PR

Source

This page reprints the English original.

pstack/skills/poteto-mode/playbooks/opening-a-pr.md (cursor/plugins 12d587d).

中文页

Opening a PR

Invoked at the end of every other playbook.

Worktree. Work from a git worktree off main. Subagents inherit it. Multiple Task calls on the same branch each get their own worktree, or git fetch && git reset --hard origin/<branch> between them. Dirty branch with unrelated work: patch out, fresh worktree, apply. Snarled worktree: reset from main, redo minimally.

Commits. Commit liberally. Rebase into small, ordered commits before opening PRs. Each commit is a future PR: landable, ordered to tell the story. Amend when the fix belongs in a just-made commit. New commit when separable.

PRs. Run /deslop from cursor-team-kit over the diff before commit. Run /no-comments before review. Write every PR title, PR description, and commit body with /technical-writing, then apply /unslop. Apply every technical-writing layer except Diátaxis. Use one word for each action, keep articles, and avoid -ing when a plain verb works.

Titles. Use Conventional Commits in the form type(scope): subject. Use feat, fix, docs, refactor, test, chore, or perf as the type. Use the changed area, such as pstack or poteto-mode, as the scope. Keep the subject short and imperative. Name a real symbol when one carries the change. For example, fix(pstack): retarget opening-a-pr babysit trigger. Do not add a trailing period.

Descriptions. The PR body is a briefing, not the lab notebook. A reviewer who has the diff should learn why the change exists, what is out of scope, and how you proved the change works. The squash commit body is the PR body. If the body would make the squash commit longer than about 40 lines, cut the body.

Use these sections in order. Drop a section when it has nothing to say.

• ## Why. State the intent and approach in one or two short paragraphs. Do not list SHAs or rebase genealogy. Do not add a “based on main” preamble.
• ## Scope. Use bullets to list real symbols and paths. Name both sides of a rename or retarget. State what is in and out only when the boundary matters. Do not write a file-by-file essay.
• ## Tradeoffs. Name only rejected alternatives that a reviewer would otherwise ask about. Skip this section when there was no real choice.
• ## Blast Radius. In one to three sentences, name who or what the change touches and why the change is safe or risky. State the continuing cost if main stays red without the fix.
• ## Verification. Name each real run path and its outcome. For a performance change, report one primary number with its unit in before → after form. Link the arena or swarm directory for the remaining evidence. Do not include sample-size methodology, swarm recitals, or metric tables.

After these sections, attach videos or screenshots when they prove a claim. Do not paste full SHAs, swarm or arena lane recitals, lever-correction essays, file-by-file checklists, or “CLEAN” verdicts. Put these details in a linked artifact. Do not use ## Summary or ## Test plan boilerplate. A commit body does not restate its subject.

Forge. Resolve the forge before the first PR operation and keep that choice for create, edit, view, watch, and merge. GitHub CLI (gh) is the default. If command -v origin succeeds and Origin can resolve the repository, prefer origin pr .... If Origin is absent or cannot resolve the repository, stay on gh and record the fallback. Do not require Graphite (gt).

Size and stacks. Prefer five narrow PRs to one large PR. A stack is a base-branch chain. The root PR targets trunk. Each child branch rebases onto its parent’s exact tip and its PR targets the parent branch. Create a child with origin pr create --status open --base <parent-branch> or gh pr create --base <parent-branch> according to the resolved forge. Retarget an existing child with origin pr edit <pr> --base <parent-branch> or gh pr edit <pr> --base <parent-branch>. Branch from trunk only for independent work. Rebase on trunk before substantial stack work.

Readiness. Open every PR ready, never as a draft. With Origin, pass --status open. With gh, omit --draft. Cloud-agent PR tools default to draft, so set draft: false on every PR creation call. If a PR still opens as a draft, run origin pr ready <number> or gh pr ready <number> according to the resolved forge. Run origin pr view <number> or gh pr view <number> before you refer to PR status.

Babysit. Opening a PR does not start a babysit. Post the URL and keep building. Finish the phase or stack first. Run a separate babysit pass only when the user asks for one after the whole stack exists. A babysit for each new PR stalls the build and spends checks on commits that later waves restart. Push back when feedback drifts from intent.

A subagent that opens a PR runs interrogate, /deslop, and /no-comments, and posts the URL. Then it returns to the parent without babysitting, unless it is an Autopilot-full or Autopilot-stack owner. That owner’s brief assigns the babysit loop and is the ask playbooks/babysit.md waits for. The owner starts the loop after its code-ready report and reports merge-ready or STACK-READY as its playbook says. The rules here and in playbooks/babysit.md that hold babysitting until a whole stack is built do not apply to that owner.