agentleFS
youknowoneyouknowone/pyre/.claude/skills/merge/SKILL.md

merge

Skill6 starsChanged 27 days agoMITView on GitHub

Plan and execute a safe merge of the current working branch into `upstream/main` by accumulating only green-test changes onto a separate `<branch>-merge` branch. Invoked via `/merge`. Use this skill whenever the user asks to "merge", "land", "prepare for merge", "cherry-pick safely", or any equivalent request to move work from a long-running branch toward `upstream/main`. The skill enforces the house policy that `pyre/check.py` must be all green, and it prefers line-level imports over whole-commit cherry-picks (bare `git cherry-pick` is only safe for trivially conflict-free, self-contained commits). Default to using this skill any time the user hints at moving work from a long-running branch toward `upstream/main`, even without explicit keywords.

57 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use addskill, apply-firmware and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • ryanportfolioSkill

    addskill

    Create, import, update, or install repo or personal skills: runtime ownership, resources, discovery checks.

    Also in 6 projects that use this

  • ryanportfolioSkill

    apply-firmware

    Bring current folder (plain folder, existing repo, old or partial firmware copy) up to full Harness Firmware in place. Mirror external repo → adopt-repo.

    Also in 6 projects that use this

  • +10 more from ryanportfolio

The file

Show its rules and text

We split this skill into the rules it gives an agent

24 rules. 0 are common, 8 are distinctive, and 16 are very specific to this project.

  • 0

    Common

    Most of the 51 edited versions we read keep these.

  • 8

    Distinctive

    This author's own choices. Worth a look.

  • 16

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  • could be automatic: a setting could enforce it
  1. Very specific:

    Keep the original working branch untouched — it remains the source of truth for "what we eventually want".

    line 16
  2. Very specific:

    When the user types /merge:

    line 20
  3. Distinctive:

    Check current state and plan.

    line 23
  4. Very specific:

    If <MERGE> does not exist:

    line 43
  5. Very specific:

    Create it at upstream/main: git branch <MERGE> upstream/main

    line 44
  6. Distinctive:

    Do not check it out yet unless the user wants to start immediately.

    line 45
  7. Very specific:

    If <MERGE> already exists:

    line 47
  8. Very specific:

    Verify it is a descendant of (or equal to) upstream/main.

    line 48
  9. Very specific:

    Check whether pyre/check.py passes on <MERGE> before adding anything.

    line 49
  10. Very specific:

    Default to line-by-line imports.

    line 66
  11. Distinctive:

    If any of those fail, fall back to line-by-line.

    line 78
  12. Very specific:

    Write the change by hand on <MERGE> — read the source from WORK, but apply it with Edit/Write onto <MERGE>.

    line 87
  13. Very specific:

    Before committing, re-read the diff against the base (git diff upstream/main -- <file>) and confirm only the intended lines moved.

    line 89
  14. Very specific:

    Run python ./pyre/check.py after every slice, no matter how small.

    line 93
  15. Distinctive:

    If the change is irreducibly unsafe on its own, mark it as "deferred" and move on to a different slice.

    line 105
  16. Very specific:

    Never "commit and fix later".

    line 107
  17. Very specific:

    When pyre/check.py is green, commit with a factual message (no speculation about goals, no Co-Authored-By but use Assisted-By, English …

    line 111
  18. Distinctive:

    When the user decides to stop (either the diff is empty or the remaining work is not safely landable):

    line 130
  19. Distinctive:

    Do not push, merge, or open a PR unless the user explicitly asks.

    line 135
  20. Distinctive:

    Prefer line-by-line slices.

    line 139
  21. Very specific:

    Never commit on <MERGE> without a green pyre/check.py immediately before.

    line 140
  22. Very specific:

    Never modify WORK from this skill — it is read-only here.

    line 141
  23. Very specific:

    Never push <MERGE> or open a PR without explicit user instruction.

    line 142
  24. Distinctive:

    Always commit after each green test — do not batch multiple slices into one commit, because a later red test cannot be bisected if slices …

    line 143

“Common” is measured: kept by at least 6 in 10 of the 51 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Safe Merge via -merge Branch

Why this skill exists

The working branch has accumulated many commits; some of them break pyre/check.py. House policy is:

pyre/check.py must be all green — no exceptions — before anything lands on upstream/main.

Cherry-picking by commit almost always breaks the build because commits depend on each other and on intermediate states that never made it through review. So we never move whole commits. We move code, one small slice at a time, and run the tests after each slice.

Keep the original working branch untouched — it remains the source of truth for "what we eventually want". The -merge branch is a clean, always-green staging area that starts at upstream/main and only grows with verified slices.

Invocation

When the user types /merge:

  1. Parse any follow-up text as scoping hints (e.g. /merge only the heapcache changes, /merge focus on blackhole.rs). Default is "work through everything safely".
  2. Check current state and plan.
  3. Execute the plan with the user.

Step 1 — Establish the -merge branch

Determine:

  • WORK = the current branch (e.g. stdlib)
  • MERGE = <WORK>-merge (e.g. stdlib-merge)
  • BASE = upstream/main

Run:

git branch --show-current            # confirm WORK
git rev-parse --verify upstream/main # confirm BASE exists
git rev-parse --verify <MERGE> 2>/dev/null   # does MERGE already exist?

This skill does not auto-fetch — upstream/main is whatever the user last fetched (they sync the upstream remote manually). If upstream/main is missing, stop and ask the user to add the remote (git remote add upstream <URL>) and fetch it; do not fall back to local main.

If <MERGE> does not exist:

  • Create it at upstream/main: git branch <MERGE> upstream/main
  • Do not check it out yet unless the user wants to start immediately. Confirm with the user before switching.

If <MERGE> already exists:

  • Verify it is a descendant of (or equal to) upstream/main. If not, surface the divergence and ask the user whether to reset it to upstream/main or continue from its current tip.
  • Check whether pyre/check.py passes on <MERGE> before adding anything.

State the plan concisely before moving code: which branch is source, which is destination, and what the user wants to land first.

Step 2 — Survey what needs to move

Work from the current state of both branches:

git diff <MERGE>..<WORK> --stat      # what's left to bring over
git diff upstream/main..<MERGE> --stat   # what's already landed safely

git diff upstream/main <MERGE> is how we track progress — it grows with each safe slice. Show the user the remaining diff bucketed by file/area so they can point at what to try first.

Step 3 — Prefer line-by-line slices; cherry-pick only when trivially clean

Default to line-by-line imports. The reason is that commits on WORK tend to:

  • Depend on earlier broken states, scaffolding, or partial refactors that never land.
  • Mix correctness fixes (safe) with speculative behavior changes (unsafe) in a single commit.
  • Split renames and follow-up cleanups across commits — taking only one leaves dangling references.

That said, git cherry-pick is acceptable for a commit that meets all of:

  • Applies cleanly (no conflict, no --strategy tricks).
  • Is self-contained — touches one concern, with no implicit dependency on other un-landed commits.
  • Has been inspected hunk-by-hunk, not just by subject line.

If any of those fail, fall back to line-by-line. When in doubt, line-by-line is always safe; cherry-pick is an optimization.

Safe slicing procedure (line-by-line path):

  1. Pick a small, self-contained change from git diff <MERGE>..<WORK> for one file. Prefer:
    • A single added/renamed helper function with no new call sites yet.
    • A bugfix hunk that does not depend on new types or new fields.
    • A pure refactor (e.g. extracted local, renamed local variable) verifiable by inspection.
    • Comment, doc, or dead-code removal.
  2. Write the change by hand on <MERGE> — read the source from WORK, but apply it with Edit/Write onto <MERGE>. Do not use git checkout <WORK> -- <file> for partial changes; that grabs the whole file and usually breaks things.
  3. For a clean whole-file import where inspection confirms the file is self-contained (e.g. an isolated new module with no existing callers on upstream/main), git checkout <WORK> -- <path> is acceptable, but verify with the test run immediately after.
  4. Before committing, re-read the diff against the base (git diff upstream/main -- <file>) and confirm only the intended lines moved.

Step 4 — Test every slice

Run python ./pyre/check.py after every slice, no matter how small. This is non-negotiable — the whole point of the -merge branch is that it is always green.

python ./pyre/check.py

Outcomes:

  • All green → commit immediately, then pick the next slice.
  • Red → do NOT commit. Either:
    • Shrink the slice further (most common fix — revert part of the change and retry).
    • Pull in the missing dependency (a helper, a type, a rename) from WORK first, then re-test.
    • If the change is irreducibly unsafe on its own, mark it as "deferred" and move on to a different slice. Tell the user which slice was deferred and why.

Never "commit and fix later". <MERGE> must stay green at every commit.

Step 5 — Commit on success

When pyre/check.py is green, commit with a factual message (no speculation about goals, no Co-Authored-By but use Assisted-By, English only):

git add <files>
git commit -m "<concise factual summary>"

Then loop back to Step 3 with the next slice.

Periodically re-run:

git diff <MERGE>..<WORK> --stat

to see what is left. The goal is to drive this diff toward empty, one green commit at a time.

Step 6 — Wrap-up

When the user decides to stop (either the diff is empty or the remaining work is not safely landable):

  • Report what landed on <MERGE> (git log upstream/main..<MERGE> --oneline).
  • Report what is deferred, per-file, with the reason it could not land.
  • Confirm the original WORK branch is untouched (git log <WORK> unchanged vs. when we started).
  • Do not push, merge, or open a PR unless the user explicitly asks.

Hard rules (recap)

  • Prefer line-by-line slices. git cherry-pick is allowed only for trivially conflict-free, self-contained commits that have been inspected hunk-by-hunk.
  • Never commit on <MERGE> without a green pyre/check.py immediately before.
  • Never modify WORK from this skill — it is read-only here.
  • Never push <MERGE> or open a PR without explicit user instruction.
  • Always commit after each green test — do not batch multiple slices into one commit, because a later red test cannot be bisected if slices are batched.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.