Split work into PRs
Turn one big change (a long branch, uncommitted edits, or both) into a few pull requests that each make sense on their own.
Tools: git (status, diff, log, switch, add, commit, push, stash), exec only for
what the git tool does not model (backup ref, hunk staging), and forge action
pr_create for the requests.
Hard rules
- No branch, commit, push or PR until the user approves the plan. Inspecting is fine.
- Never discard work. No
reset --hard,checkout -- .,clean,branch -D, force push orstash dropwithout the user's explicit approval for that exact command. - Recoverable snapshot first, before the first write:
ts=$(date +%Y%m%d-%H%M%S) snap=$(git stash create) # empty output means the tree is clean git update-ref "refs/backup/pre-split-$ts" "${snap:-HEAD}"git stash createrecords the uncommitted work as a commit without touching the tree or the stash list. Tell the user the ref name; it is how they get everything back (git stash apply refs/backup/pre-split-<ts>orgit switch -c rescue refs/backup/pre-split-<ts>). - Stage only the files or hunks named in the approved slice. Never
git add -A,git add .orcommit -a. - Keep the backup ref at the end. Only the user deletes it.
1. Check the state
- Default branch:
forgereads it for PRs; locallygit symbolic-ref refs/remotes/origin/HEAD(fall back tomain/master).git fetchfirst so the comparison is fresh. - What differs from it:
git log --oneline <default>..HEAD,git diff --stat <default>...HEAD, plus uncommitted work (git action=status, git action=diff, staged and unstaged). - Ownership signals:
CODEOWNERS(.github/,.gitlab/, root,docs/), top-level folders, packages in a monorepo. Changes owned by different reviewers usually belong in different PRs.
2. Propose slices
- One line per slice: a PR title, and a one-line scope when the title alone is unclear.
- List the files (and, when a file is shared, which hunks) in each slice.
- Default: independent PRs, each based on the default branch and mergeable in any order.
- Stack (PR 2 based on PR 1's branch) only for a real dependency (PR 2 does not build or pass tests without PR 1). Say why.
- Several slices: add a small diagram of the slices and their dependencies (archify HTML+SVG when the user wants a visual, otherwise a short mermaid block).
- Name what stays out (debug files, unrelated edits) as "leftovers".
- Ask: "OK to go with this plan?" and wait.
3. Execute (after approval)
For each slice, in dependency order:
git action=switch create=true name=<branch> commit=<base>(base = default branch, or the previous slice's branch when stacked).- Bring the slice's changes in:
- whole files from the snapshot:
git checkout refs/backup/pre-split-<ts> -- <paths>(exec), or from the original branch:git checkout <source-branch> -- <paths>; - part of a file: write the slice's hunks to a patch file and stage only them:
The git tool'sgit diff <base> refs/backup/pre-split-<ts> -- path/file.py > /tmp/slice-1.patch # edit the patch down to the hunks of this slice, then: git apply --cached --check /tmp/slice-1.patch && git apply --cached /tmp/slice-1.patchaddstages whole paths;git apply --cachedthrough exec is the non-interactive hunk staging (neveradd -p, it hangs without a TTY).
- whole files from the snapshot:
git action=add paths=[...]for whole files,git action=diff staged=trueto check exactly what is staged, thengit action=commit message="...".- Run the project's quick checks (build / tests) when they exist.
git action=push set_upstream=true, thenforge action=pr_create title=... body=... base=<base>. The body says what the slice does and, when stacked, which PR it builds on.
After the last slice, switch back to the branch the user was on.
4. Report
- Each PR: title and URL, independent or stacked on which one.
- Leftovers: what was not included and where it still lives (the original branch, the working tree, or the backup ref).
- The backup ref name, kept on purpose.
