draft-prs

name	draft-prs
description	Manages draft status for stacked PRs. Use when creating any PR in a stack (mark non-current PRs as draft), and when a base PR merges (promote the next PR to ready). Prevents reviewers from seeing PRs that depend on unmerged work.

Draft PR Management

Controls draft status across a stacked PR chain so reviewers only see PRs that are ready.

Rule

Only the bottom-most unmerged PR in a stack should be open (ready for review). All PRs above it must be draft until their base merges.

Example:

PR 12 feat/flow-creation       → OPEN (base is main, ready for review)
PR 13 feat/flow-node-editor    → DRAFT (base is PR 12, not yet merged)
PR 14 feat/flow-connections    → DRAFT (base is PR 13, not yet merged)
PR 15 feat/flow-variations     → DRAFT (base is PR 14, not yet merged)

After PR 12 merges:

PR 13 feat/flow-node-editor    → OPEN (rebased onto main, ready for review)
PR 14 feat/flow-connections    → DRAFT (still waiting)
PR 15 feat/flow-variations     → DRAFT (still waiting)

When Creating a PR in a Stack

The current base PR (ready for review)

gh pr create \
  --title "<title>" \
  --base <base-branch> \
  --body "$(cat <<'EOF'
## Summary
- <bullet>
- <bullet>

## Stack position
This is PR N of M in the `<feature-name>` stack.
Previous: #<prev-pr> | Next: #<next-pr> (draft)

## Test plan
- [ ] <verification step>
EOF
)"

Do NOT pass --draft for the current base PR.

Downstream PRs (not yet ready for review)

gh pr create \
  --draft \
  --title "<title>" \
  --base <base-branch> \
  --body "$(cat <<'EOF'
## Summary
- <bullet>

## Stack position
This PR is **draft** -- waiting for #<base-pr> to merge first.
Stack: #<base-pr> → this PR → #<next-pr>

## Test plan
- [ ] <verification step>
EOF
)"

Always include the stack position context so reviewers understand the dependency.

When a Base PR Merges

After the user reports a PR is merged:

1. Identify the next PR in the stack (first draft entry in .claude/stack.json)

2. Rebase it onto main:

   git fetch
   git checkout <next-branch>
   git rebase main
   git push --force-with-lease --force-if-includes
   

3. Update its base on GitHub:

   gh pr edit <next-pr-number> --base main
   

4. Promote from draft to ready:

   gh pr ready <next-pr-number>
   

5. Update .claude/stack.json via the jpegg:pr-stack skill

6. Report: "PR # promoted to ready for review: "

Updating Stack Position Text in PR Bodies

When a PR moves from draft to ready, optionally update its description:

gh pr edit <number> --body "$(cat <<'EOF'
## Summary
<existing content>

## Stack position
Base: main (previously #<merged-pr>, now merged)

## Test plan
<existing content>
EOF
)"

This keeps the PR body accurate for reviewers who weren't watching from the start.

Checking Current Draft Status

gh pr list --json number,title,isDraft,baseRefName,headRefName \
  --jq '.[] | "\(.number) \(if .isDraft then "[DRAFT]" else "[OPEN]" end) \(.headRefName) → \(.baseRefName) \(.title)"'

Use this to audit whether the stack matches the expected draft pattern.