split-pr

Files (8)

• SKILL.md
• guide.md
• split-plan-format.md · references/
• split_plan.py · scripts/
• split_plan_git.py · scripts/
• split_plan_model.py · scripts/
• split_plan_stack.py · scripts/
• split_plan_test.py · scripts/tests/

SKILL.md (first lines)

# Split PR

```text
INPUT $ARGUMENTS = [split] [--base origin/<branch>] [--publish] [--multi-parent wait|merge]
                 | restack [<plan.json>] [--publish]
mode = restack when the first word is `restack`, otherwise split.
--publish: open or update PRs. Without it, branches stay local.

HELPER  H = python3 skills/split-pr/scripts/split_plan.py
PLAN    temp/split-pr/<source-branch with / replaced by ->/plan.json

RULES
- Read guide.md before classifying parts or dependencies.
- Read references/split-plan-format.md before writing the plan.
- Edit PLAN by hand only in CLASSIFY and CONFIRM (including a return to CONFIRM
  from BUILD); everywhere else it changes only through `H record`. Never
  hand-edit onto, tip, pr or landed.
- Never push to `upstream`, never push the source or base branch, never
  force-push without `--force-with-lease=<ref>:<expected sha>`.
- Never delete the source branch, a part branch, or a remote branch.
- Preserve unrelated changes: never stash, reset, or switch branches over
  tracked dirty files in the user's worktree. Build parts in separate worktrees.
- Any helper exit code other than 0 stops the run; fix the plan or the branch
  and rerun the helper. Never edit around a failed check.
```

## Split mode

```text
========== PREFLIGHT ==========
repo = git rev-parse --show-toplevel
source = git branch --show-current
ERROR if source empty (detached HEAD).
git fetch origin
base_ref = --base or origin/master; ERROR unless it resolves. Never infer it
  from a remote's symbolic HEAD.
ERROR if source equals base_ref without `origin/` (splitting the base branch).
base_sha = git merge-base <base_ref> HEAD
source_sha = git rev-parse HEAD
ERROR if tracked changes are uncommitted: everything to split must be committed.
ERROR if git rev-list --merges <base_sha>..HEAD is nonempty (linearize first).
IF PLAN exists: STOP. Offer restack mode when its source.branch equals source;
  otherwise another branch shares PLAN's slug: report the collision.

========== CLASSIFY ==========
Inspect git log --reverse --stat <base_sha>..HEAD and every commit's diff.
Group commits into parts by purpose (guide.md "Parts"). A commit that serves
two parts is split by hunk; list it in both parts.
For each pair of parts, decide depends_on from evidence (guide.md
"Dependencies are proven, not guessed"). Commits that belong to no part go to
left_on_source with the reason, recorded in PLAN.
Name branches `codex/<topic>` unless the user gave exact names.
multi_parent = --multi-parent or `wait`.
Write PLAN. Run:
  H check PLAN      # schema, coverage of every source commit, cycles
  H probe PLAN      # git replay per part, with and without its parents
WHILE probe reports `missing-dependency`:
  add the dependency named in `overlaps` or regroup; rerun check and probe.
FOR each part with status `build-check-dependency`:
  prove it (guide.md); drop the edge if the part builds and passes alone.
IF a part can only become independent through a redesign:
  STOP and explain; do not invent a split.

========== CONFIRM ==========
Run H render PLAN and show its output verbatim: shape, order, base, depends on,
commits, file count and +/- lines per part, the source total, files per part,
and the mermaid graph. For any part that is still large, offer splitting it
further by sub-purpose (guide.md "Part size"). For a part with two or more parents,
state the policy and its trade-off (guide.md), and offer linearizing when it
fits. Wait for the user's confirmation. Any change: edit PLAN, rerun check,
probe, render, and confirm again.

========== BUILD (dependency order from `H check`) ==========
FOR part in order:
  open = parents not landed
  IF open empty:     start = base_sha
  IF one open:       start = refs/heads/<parent branch>
  IF several open:   in a detached scratch worktree at the first parent:
                       git merge --no-ff -m "chore: integrate <ids> for <id>" <other parent branches>
                     start = that merge commit (keep its SHA as onto)
  ERROR if <branch> already exists locally or on origin.
  git branch --no-track <branch> <start>
  Invoke `worktree-new <branch>`: it checks out the existing branch in a new
  worktree and provisions its cargo dependencies (plain `git worktree add`
  alone skips that provisioning).
  Reconstruct the part: git cherry-pick <commits>; for hunk-split commits apply
  only this part's hunks and commit them with the original subject. Never drop
  or duplicate a hunk.
  Verify in that worktree:
    git diff --check <start>...HEAD
    cargo check, plus focused tests for the touched modules (unset BUS_* and
    HERDR_* for test runs, including retained pane/session compatibility keys);
    for skill or script parts, their python suites.
  IF verification fails because the part needs another part's code:
    the dependency was missed: STOP building, add the edge, back to CONFIRM.
  H record PLAN --part <id> [--onto <merge sha> for several open parents]
Run H coverage PLAN. `fail` means a hunk was dropped, duplicated across parts,
built into the wrong part, or a stray change was added: the union of the part
branches differs from the source tree without the left_on_source commits, the
parts' own diffs (lines and file modes) do not sum to that tree, or a part
without hunk-split commits differs from its commits replayed onto its base. Fix the branch and rerecord.
`review-left-on-source` lists the files the left_on_source commits leave
different from the source. Coverage cannot tell which part a hunk of a
hunk-split commit belongs to (the plan does not record it): for each part with
such a commit, read git diff <onto>...<branch> and confirm every hunk serves
that part's purpose.

IF --publish absent: go to RETURN.
```

## Publish

```text
Publish in waves. The main agent runs the waves; no script orchestrates them.
WHILE some part is unpublished and not waiting:
  wave = every unpublished part whose parents all have a recorded PR or landed
         (in parallel: all parts in the first wave; in a train: one part per
         wave, bottom first; in a mixed graph: every part whose parents are done)
  Skip parts whose base is a merge (render's Base column) under

From asura1234/bus, Apache-2.0.

More from asura1234/bus