Frb PR Chain Split

1 When to use

• Use this skill while developing or reviewing a flutter_rust_bridge PR when part of its diff is independent of the PR's stated objective.
• Split the independent work proactively. Do not wait for the user to notice the mixed scope.
• Treat a change as independently landable when it:
  • has a coherent behavior or maintenance objective of its own;
  • can be implemented and validated against the current default branch;
  • does not require the main task's API, schema, generated output, or version change;
  • leaves the main PR smaller and easier to review.
• Keep inseparable companion changes in the main PR. Generated snapshots, tests, and documentation required by the main change are not independent merely because they touch different files.

2 Choose the chain boundary

Classify every suspicious change before moving commits:

• Prefer the smallest coherent predecessor, not the smallest textual diff.
• Create several predecessor PRs when the extracted work contains multiple independent contracts.
• Order predecessors by dependency. Do not infer order from commit timestamps.

3 Build each predecessor

• Fetch the canonical default branch before creating branches.
• Create the first predecessor from the current default branch.
• Create each later predecessor from the preceding predecessor branch.
• Reconstruct the coherent final delta. Do not blindly cherry-pick commits that mix predecessor and main-task changes.
• Include the predecessor's own tests and documentation.
• Validate the predecessor independently before pushing.
• Read frb-prepare-pr for generation, lint, test, and review requirements.
• Use one branch and one PR per independently landable unit.
• Push every chain branch to the same repository as the main PR. GitHub cannot use an unpushed local branch as a PR base.

4 Construct the GitHub PR chain

• Build a stacked branch chain, not sibling PRs that all target the default branch:

master <- predecessor-a <- predecessor-b <- main-task

• Use GitHub's official github/gh-stack extension through gh stack.
• Use gh stack for every stack operation: initialization, restructuring, linking, submission, synchronization, rebasing, pushing, and verification.
• Never construct or maintain a stack with gh pr create --base, gh pr edit --base, direct API base edits, or branch ancestry alone.
• Git commands may prepare the commits and linear branch ancestry, but the result is not complete until gh stack creates or updates the native GitHub stack object.
• Check and install the extension when necessary. The extension requires gh 2.0 or later; a missing gh stack command normally means the extension is absent, not that core gh is outdated.

gh stack --help
gh extension install github/gh-stack

• For an unpublished main branch, branch it directly from the final predecessor.
• Initialize and submit a new local stack with gh stack init and gh stack submit.
• For an already published main PR:
  • create a timestamped backup tag before non-trivial history work;
  • record the original final tree and three-dot PR diff;
  • restack the main branch onto the final predecessor with a fully linear history;
  • do not introduce merge commits because native GitHub stacks require linear ancestry;
  • compare the rebuilt tree and PR delta with the recorded originals before pushing;
  • use --force-with-lease only after those checks when published history must be rewritten.
• Adopt existing branches or PRs with gh stack link. It pushes branches, creates missing PRs, corrects their base branches, and creates the native GitHub stack object.
• Create and connect a new stack with commands shaped like:

gh stack init --base master <predecessor-branch> <main-task-branch>
gh stack submit

• Adopt already prepared branches or existing PRs with:

gh stack link --base master <predecessor-branch> <main-task-branch>

• Verify local ancestry, native stack metadata, and PR bases:

git merge-base --is-ancestor <predecessor-branch> <main-task-branch>
gh stack view --json

• Compare three-dot diffs after constructing the chain:
  • <previous-branch>...<predecessor-branch> contains only that predecessor;
  • <final-predecessor-branch>...<main-task-branch> no longer contains the extracted work;
  • the final main-task tree is unchanged except for intentional cleanup.