shepherd-pull-requests

name	shepherd-pull-requests
description	How a Shepherd session opens a pull request - exactly one PR per session, what to do when the work is too large for one (promote to an epic, or ship a slice plus a follow-up issue), and how to declare manual operator steps so they survive merge. Load before running `gh pr create`, or as soon as a task looks like it needs more than one PR.

Opening a pull request from a Shepherd session

A Shepherd session tracks one pull request. This is the mechanism talking, not a style preference: PR detection, the critic, the merge train and the Owed lens are all keyed to a single PR per session.

Exactly one PR

When you open a pull request, open exactly one — never a second, and never label work "PR 1 of N." This holds even when the task or its issue describes multiple parts, phases, or "Part A / Part B."

If the work is genuinely too large for one cohesive PR, pick ONE of:

• (a) Promote to an epic. Convert the issue into an epic — create one child issue per intended PR and mark the parent body so Shepherd recognizes it (shape below) — open NO pull request yourself, then STOP and tell the operator the epic is ready to drain. Shepherd drains each sub-issue as its own session and its own PR, but that drain is operator-started: you cannot trigger it yourself.
• (b) Ship one PR + file a follow-up. Complete and open a single cohesive PR for the slice you can finish, then gh issue create a follow-up issue capturing the remainder for a later agent, and reference it from the PR body. This is the always-safe default.

Never split the work across two PRs from this one session.

The epic shape (option (a))

Shepherd recognizes an epic ONLY structurally — the parent issue's body must reference each child's REAL issue number. Create the child issues first (gh issue create), capture their numbers, then edit the parent body to add EITHER a fenced dag block, e.g.:

#12
#13 <- #12

(one #<n> line per child; #<n> <- #<m> when #n is blocked by #m), OR a task-list with one - [ ] #12-style line per child issue. This body marker is MANDATORY even when the children have no dependencies. NOT recognized as an epic: an epic label, an [EPIC] title prefix, or a prose checklist without #<n> issue references.

Manual operator steps

Before you open the pull request, declare any MANUAL OPERATOR STEPS the change implies — work a human must do around merge/deploy that the diff itself cannot perform (flip a feature flag, set an env var, run a one-off backfill/migration, restart a worker, DNS cutover, seed a record). Shepherd parses these from the PR body and surfaces them on the Owed lens so they survive merge and teardown.

Declare them in the PR body with EITHER carrier:

• A fenced block — each - [ ] line is one step:

- [ ] Set the FEATURE_X env var in production
- [ ] POST-MERGE: Run the data backfill once the PR is live

• Or column-0 Manual-Step: trailer lines (flush-left, outside any fence), e.g. a line reading exactly Manual-Step: Rotate the signing key.

Prefix a step with POST-MERGE: when it must happen AFTER the PR merges.

DEFAULT TO DECLARING NOTHING. Most PRs need NO manual steps. Add a step ONLY for a real out-of-band action a human must take; if merging fully completes the change, OMIT the carrier entirely. NEVER invent steps to fill the block — a spurious step is worse than none. When in doubt, declare nothing.

If you have already opened the PR when you realize a step is owed, add it with gh pr edit --body rather than opening a second PR.