Skip to content

docs(pstack): default to one PR per requested change - #522

Open
dg-spcx wants to merge 3 commits into
cursor:mainfrom
dg-spcx:pstack/one-pr-default
Open

dg-spcx wants to merge 3 commits into
cursor:mainfrom
dg-spcx:pstack/one-pr-default

Conversation

@dg-spcx

@dg-spcx dg-spcx commented Oct 8, 2026 •

Copy link
Copy Markdown

Why

Opening a PR told agents to prefer five narrow PRs to one large PR. In real use, operators kept collapsing agent-built stacks of narrow PRs back into one PR, so the default produced work they undid. The new default is one PR per requested change, with a stack only when a measured collision forces it.

What changed

  • Size and stacks in opening-a-pr.md now opens with the one-PR default and names the two collisions that justify a split.
  • Feature, Visual parity, the multi-phase plan, and figure-it-out drop wording that split one change into several PRs.
  • The guide and the /poteto-help recipes stop asking for many small PRs. The version moves to 0.15.16.

Scope

  • Covers every pstack passage that set how many PRs one change becomes.
  • Leaves commit and verification granularity alone, such as the sequence-verifiable-units principle and its commit order.
  • Leaves queues of separate changes alone, such as Autopilot-full, Autopilot-stack, and Orchestrate.

Blast Radius

Agents that run poteto-mode open one PR per change and stack only on a named collision. Stack mechanics and the autopilot queues do not change.

Verification

  • node scripts/validate-plugins.mjs passes.
  • check-plan.mjs on the multi-phase plan skeleton reports the same single unfilled-placeholder problem as trunk.
  • A search of pstack/ for "five narrow", "small verifiable PRs", "future PR", and "Stack follow-ups" returns nothing.

Note

Low Risk
Documentation and agent playbook guidance only; no product code or runtime behavior changes beyond how poteto-mode agents are instructed to open PRs.

Overview
pstack now tells agents to open one PR per change the operator asked for, with small ordered commits inside it, instead of defaulting to many narrow PRs or stacks.

The Size and stacks section in opening-a-pr.md is the anchor: split into a stack only when a measured collision forces it (e.g. an open PR rewrites the same hunk and must land first, or a part needs its own rollout). “Easier to review” or fewer files is no longer a reason to split. Related playbooks (feature, visual-parity, multi-phase-plan), figure-it-out, the user guide, and poteto-help recipes drop “small verifiable PRs,” per-component PRs, and “stack follow-ups” language while keeping commit and verification granularity (sequence-verifiable-units) unchanged.

Plugin version bumps to 0.15.16.

Reviewed by Cursor Bugbot for commit 1d2de01. Bugbot is set up for automated code reviews on this repo. Configure here.

Size and stacks now defaults to one PR per change the operator asked
for, with small ordered commits inside it. A stack needs a measured
collision. The Commits paragraph no longer calls each commit a future PR.
Feature drops "Stack follow-ups", and Visual parity opens one PR
instead of one per component. The multi-phase plan treats a PR as one
requested change and names the collision behind each split.
figure-it-out asks for verifiable units, not landable ones. The guide
and the /poteto-help recipes stop asking for many small PRs.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant