Stacked Batch Prs

stacked-batch-prs

Template skill (doc 02, doc 06). When many batches each add pages AND touch the same shared files (the index, a queue, a log), parallel branches off main collide on every merge. Stacking each branch off the prior tip removes the conflict — at the cost of a sharp hazard: merging the stack out of order can strand content off main. This skill is the discipline that makes stacking safe.

Trigger

/stacked-batch-prs <batch-id> [--base <prior-tip-or-main>]

Preconditions

1. The index/catalog is auto-generated from page frontmatter — never hand-edited. (Hand-editing the index is the shared-file conflict generator.)
2. A human merge gate exists; agents open PRs, humans merge.
3. The prior batch's branch tip is known (the base for this batch's branch).

Steps

1. Branch off the prior tip, not main. git checkout -b batch-<id> <prior-tip>. Each batch sees the prior batch's index/shared-file state, so re-generating the index produces a clean superset diff instead of a conflict.
2. Add pages; regenerate, never hand-edit, the index. Run the index generator so the index is a pure function of frontmatter. A hand edit here re-introduces the conflict the stack exists to avoid.
3. One PR per batch, targeting the prior batch's PR branch (the stack), with a clear "stacked on #" note so the reviewer/merger knows the order.
4. Merge bottom-up, in order. The human merges the oldest open PR in the stack first. Never merge a higher PR before the one beneath it.
5. GUARD the merge cascade. A top stacked PR can auto-target an already-merged intermediate branch; merging it then lands content onto a dead branch, not main. After every merge in the stack: verify main's tree actually contains the merged pages (git fetch && git ls-tree origin/main -- <paths>), and re-target the next PR's base to main (or the new tip) if its base was just merged.
6. Rebase trailing PRs if a base moved. If an earlier PR was squashed/rebased, rebase the rest of the stack onto the new main tip before continuing.

Verification

• After each merge, the merged batch's pages are present in origin/main's tree (not just in a merged-away intermediate branch).
• The index on main is the generator's output for the current frontmatter set (re-run the generator → empty diff).
• No PR merged out of stack order; no content stranded off main at campaign end.

Cleanup

• Delete merged batch branches. Confirm origin/main is the single source of truth and every batch's pages are reachable from it.

Incident appendix