scripts: add merge-branches Claude Code skill

[AvivYossef-starkware]

No description provided.

[reviewable-StarkWare]

This change is 

[AvivYossef-starkware]

• scripts: add merge-branches Claude Code skill #14019 👈 (View in Graphite)
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[cursor]

PR Summary

Low Risk
Low risk: adds a new Claude command markdown guide only, with no runtime code changes.

Overview
Adds a new Claude Code command guide, /.claude/commands/merge-branches.md, documenting an end-to-end workflow for running scripts/merge_branches.py, resolving merge conflicts interactively, running cargo check to catch silent API skews, committing a separate fix_conflicts change via gt/git, and posting per-conflict inline PR review comments tagging the authors involved.

^{Reviewed by Cursor Bugbot for commit 88fd4ee. Bugbot is set up for automated code reviews on this repo. Configure here.}

[dorimedini-starkware]

@dorimedini-starkware reviewed 1 file and all commit messages, and made 4 comments.
Reviewable status: all files reviewed, 4 unresolved discussions (waiting on AvivYossef-starkware).

---

.claude/commands/merge-branches.md line 43 at r1 (raw file):

If the script ran with `gt`-untracked state, run `gt track --parent <dst-branch>` so subsequent `gt modify`/`gt submit` work.

---

this script can fail. one reason I can think of: file deleted on main but edited on main-v0.14.2.
should you remark on that in the skill?

Code quote:

## Step 2: Fetch and run the merge script

```bash
git fetch origin <src-branch> <dst-branch>
python3 scripts/merge_branches.py --src <src-branch> --dst <dst-branch>

Capture the script's output. From it, extract:

• The new merge branch name (<user>/merge-<src>-into-<dst>-<timestamp>).
• The PR URL / number created by gh pr create.
• The list of conflicted files (printed under git status -s | grep -E ...).

If the script ran with gt-untracked state, run gt track --parent <dst-branch> so subsequent gt modify/gt submit work.

---

___
*[`.claude/commands/merge-branches.md` line 45 at r1](https://reviewable.io/reviews/starkware-libs/sequencer/14019#-Ot30dGFAVaxuh217u8L:-Ot30dGFAVaxuh217u8M:bg3ee1n) ([raw file](https://github.com/starkware-libs/sequencer/blob/bd0770b9c0885137d5bf6a0302a86ebeef0548d1/.claude/commands/merge-branches.md#L45)):*
> ```Markdown
> ---
> 
> ## Step 3: Enumerate conflicts
> ```

before this phase: someone needs to mark all changes as viewed in the PR, otherwise you won't get a separation into revisions for the review



_Code quote:_
```Markdown
## Step 3: Enumerate conflicts

---

.claude/commands/merge-branches.md line 123 at r1 (raw file):

---

## Step 7: Commit and push via Graphite

you mention graphite everywhere - I would avoid it.

1. I don't use graphite for merges, just plain git
2. What if we move to some other tool in the future?

you can add an "Ask the user which git tool to use" at the top or something, but please remove explicit graphite usage directives

Code quote:

## Step 7: Commit and push via Graphite

---

.claude/commands/merge-branches.md line 131 at r1 (raw file):

Use --force — the merge script already pushed the branch, so Graphite will refuse a normal submit. The local state is authoritative at this point.

1. do you need to be so explicit as to how to commit and push?
2. what if not using graphite?
3. are you 100% sure you need --force here...? I edit stacks all the time, gt submit works fine

Code quote:

```bash
git add <resolved-files>
gt modify -cam "fix_conflicts"
gt submit --force

Use --force — the merge script already pushed the branch, so Graphite will refuse a normal submit. The local state is authoritative at this point.

<!-- Sent from Reviewable.io -->

[AvivYossef-starkware]

🤖 Replies drafted by Claude on behalf of @AvivYossef-starkware. Each thread below quotes the Reviewable discussion URL so it threads back to your original comments. Changes addressing 1, 2, and (4.3) are in 21f015c.

[dorimedini-starkware]

@dorimedini-starkware reviewed 1 file and all commit messages, made 2 comments, and resolved 6 discussions.
Reviewable status: all files reviewed, 3 unresolved discussions (waiting on AvivYossef-starkware).

---

.claude/commands/merge-branches.md line 133 at r3 (raw file):

```bash
git add <resolved-files>
gt modify -cam "fix_conflicts"

1. doesn't modify amend the merge commit? or does the -c add a new commit on the branch?
2. best practice to use chore scope in the fix commit

Suggestion:

```bash
git add <resolved-files>
gt create -am "chore: fix_conflicts"

[AvivYossef-starkware]

@AvivYossef-starkware made 2 comments.
Reviewable status: 0 of 1 files reviewed, 3 unresolved discussions (waiting on dorimedini-starkware).

---

.claude/commands/merge-branches.md line 133 at r3 (raw file):

Previously, dorimedini-starkware wrote…

1. doesn't modify amend the merge commit? or does the -c add a new commit on the branch?
2. best practice to use chore scope in the fix commit

-cam create a new commit
chore: fix conflict is not allowed commit message

[dorimedini-starkware]

@dorimedini-starkware reviewed 1 file and all commit messages, and resolved 3 discussions.
Reviewable status: complete! all files reviewed, all discussions resolved (waiting on AvivYossef-starkware).