PR Commit Splitter Draft PR Mode

Create reviewable commit history from one large PR without force-pushing the original review branch.

When To Use

Use this flow when at least one condition is true:

• 12 or more changed files
• 500 or more changed lines
• The user explicitly asks for logical commit splitting
• The user wants the original PR branch left untouched

Required Tools

• git
• gh

Stop if GitHub CLI is not authenticated or the current repository is not connected to the target PR.

Safe Workflow

1. Capture baseline state:

• git status --short
• git fetch origin
• gh pr view --json number,title,url,headRefName,baseRefName
• git stash list
• git branch --show-current

1. Resolve the real PR context:

• Treat the PR head branch as read-only.
• Treat the PR base branch as the source for the draft split branch.
• Create a draft split branch name like pr-<number>-split-draft.

1. Create the scratch branch from the latest base:

• git switch -c pr-<number>-split-draft --track origin/<baseRefName> when no local branch exists.
• If the branch already exists locally, reset expectations first and confirm it is safe to reuse before continuing.

1. Propose commit groups by file sets, not line-by-line by default.
2. Rebuild the PR as a review stack on the scratch branch:

• For each group, restore files from the real PR head branch onto the scratch branch:
• git restore --source origin/<headRefName> --staged --worktree -- <group files>
• Commit each group with a coherent message.

1. Verify the scratch branch reproduces the real PR tree:

• Compare trees directly, not commit history:
• git diff --stat origin/<headRefName> HEAD
• Stop if the final tree differs.

1. Push the scratch branch:

• git push -u origin pr-<number>-split-draft

1. Open a draft PR against the same base branch:

• gh pr create --draft --base <baseRefName> --head pr-<number>-split-draft

1. Comment on the original PR with:

• The draft PR URL
• The ordered commit list
• Per-commit compare links for review

1. Return to the original branch when finished.

Default Commit Grouping Order

1. Domain or contract changes
2. Persistence or infra changes
3. Runtime handlers, controllers, or workers
4. Application wiring
5. Tests
6. Tooling or chore files

Keep each commit independently reviewable.

Comment Payload

Post one concise comment on the original PR with this structure:

Created a draft review stack for this PR:
- Draft PR: <url>
- Commit 1: <subject> (<compare-url>)
- Commit 2: <subject> (<compare-url>)
- Commit 3: <subject> (<compare-url>)

The original PR branch was left unchanged.

Prefer compare links of the form:

• First commit: <repo>/compare/<base_sha>...<commit_sha>
• Later commits: <repo>/compare/<previous_commit_sha>...<commit_sha>

Prehook Failure Recovery

If a commit fails because hooks need dependent files:

1. Read the hook output.
2. Restore only the missing files from origin/<headRefName>.
3. Add them to the same commit and retry once.
4. If the dependency boundary becomes unclear, stop and explain the blocker.

Safety Rules

• Never force-push the original PR branch.
• Never rewrite the original PR branch in place.
• Do not use destructive commands such as git reset --hard.
• Do not drop or overwrite user stash entries.
• Stop immediately if branch reuse, tree verification, or PR comment targeting is ambiguous.