agentleFS
kekzlkekzl/imp/.claude/skills/shipping-prs/SKILL.md

shipping-prs

Skill83 starsChanged 2 days agoMITView on GitHub

Open, merge, release a PR - branch off main, gh pr create, auto-merge, PR body, CHANGELOG entry, tagged release. "PR stuck BLOCKED", "last commit didn't land", "which check is required", "check-release failed", "STALE.md blocks git pull". Not build/test (building-and-testing), not perf baseline (benchmark-cuda).

  • Reads credentials
  • Commits and pushes

The file

We split this skill into the rules it gives an agent

3 rules. About 0 are common, 0 are distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈0

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    After the merge: git log -1 --stat origin/main.

    line 23
  2. Very specific:

    Never fix a red advisory check by pushing into an armed PR: disable, fix, push, re-arm (a red Mock API contract on #1803).

    line 26
  3. Very specific:

    Every paragraph carries a number, a path or a decision.

    line 48

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “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

Shipping PRs & Releases - imp

Hard rules

#RuleDetail
1Branch off fresh origin/main, gh pr create --base main, NEVER stackgit fetch origin && git switch -c <topic> origin/main. Stacking on a squash repo caused recovery-PR cascades. Fewer, batched PRs.
2main merges are SQUASHPR title = final commit subject ... (#NNNN) = the CHANGELOG line at the release cut.
3Required check = Build (ruleset 14716423)Static gates block inside it since #1527 (scripts/ci_static_gates.sh: filesize, lanes, entrypoint, alloc, kernels, launchguards, docs, citations, hygiene). Advisory: Lint, Mock API contract, Real API contract (model-less), clang-tidy, Sanitizers. Test lanes is its own check (#1770). Read gh pr checks <n> after the merge too.
4PRs do not edit CHANGELOG.mdUntil 2026-11-15 every merged PR dirtied every open PR through it (263 of 374 commits in 30 days). PRs that share no file may be in flight together; a conflict: resolve, git commit (hook: make preflight, ~20 s).
5Perf- or VRAM-moving change refreshes tests/perf_baseline.json IN THE SAME PR and says soGate 8% decode / 8% prefill / 10% own_peak_mb; scripts/gen_perf_baseline.sh (benchmark-cuda).

The auto-merge race

auto-merge.yml arms gh pr merge --auto --squash --delete-branch the moment a non-draft owner PR is opened (opened / ready_for_review / reopened). The squash fires the instant Build is green. Armed with the AUTO_MERGE_TOKEN PAT the merge starts CI on main and deletes the branch; on the GITHUB_TOKEN fallback it does neither (#2141-#2147: 0 of 7), so run gh workflow run CI --ref main after a release merge.

  • Push ALL commits before gh pr create. Draft PRs are not armed.
  • After the merge: git log -1 --stat origin/main; when a late commit changed a NUMBER, grep main for the corrected value (#1081 shipped disproved figures; #1082 fixed them). Lost commit precedent: a5403bd5 in #718.
  • Late commit sequence: gh pr merge --disable-auto <PR> FIRST, edit, make verify-fast, git push, gh pr merge --auto --squash --delete-branch, verify the squash.
  • A new topic that touches a file of a PR whose auto-merge is in flight starts after that merge (#1516 born conflicted 29 min after #1515, through CHANGELOG.md, which PRs no longer edit).
  • Never fix a red advisory check by pushing into an armed PR: disable, fix, push, re-arm (a red Mock API contract on #1803).

Ship sequence

git fetch origin && git switch -c <topic> origin/main
# work; then:
make preflight                                     # CPU only: static gates, tidy + format on changed lines, actionlint
make verify-fast                                   # measures imp:test; rebuild first (make build)
git push -u origin <topic>                         # NO --no-verify. scripts/pre-push.hook: make preflight; GPU verify-fast only with IMP_HOOK_GPU=1
gh pr create --base main --title "<squash subject>" --body-file <file>
git log -1 --stat origin/main                      # after merge
  • git push | tail swallows the gate block (it prints BEFORE the git lines); read the full output.
  • IMP_HOOK_GPU=1 git push while your own verify-fast runs collides on the GPU; without it the hook touches no GPU.
  • docs_lint.py writes docs/audit/docs-rewrite/STALE.md only with --write-stale; hooks and CI never touch it (#2194).
  • Moving text from docs/ROADMAP.md to docs/plans/ rewrites relative links (](MODELS.md) -> ](../MODELS.md)); make preflight (both hooks) runs hygiene, CI Release hygiene too. Local: docker run --rm -v $PWD:/src -w /src -e HOME=/tmp imp:toolchain bash -c 'git config --global --add safe.directory /src; bash scripts/ci_static_gates.sh hygiene docs citations'.
  • PR monitors: pgrep -f "<string>" matches the monitor's own shell; stop an old monitor before starting a second on the same PR.

The PR body

Every paragraph carries a number, a path or a decision; reasoning goes to docs/ and the PR links it.

## <change>        one section per topic, bullets under it
| | before | after |    a table wherever a count or a timing moved
## Gate            the measured block, pasted from the captured run, nothing wrapped around it
Not in here:       one line: what a reviewer would look for and not find
  • Capture the gate output to a file, then paste. Never type gate numbers from memory (three wrong PR bodies in one day: #1664, #1666, #1689).
  • Cut: the sentence that sets a finding up, the retelling of how a bug was found, reading instructions for the numbers. #1531 went 162 -> 57 lines with no fact lost. Same for commit messages.

CHANGELOG

  • The PR title is the entry: type(scope): what changed for the reader, the checkable number. feat -> Added, fix -> Fixed, perf / refactor / build -> Changed, docs / test / ci / chore -> Internal, type!: -> Breaking. Plain punctuation; every number names model, quant, unit.
  • The release cut writes the section: python3 tools/changelog_release.py --version X.Y.Z --since vPREV (--dry-run prints it).
  • Hand entries under [Unreleased] only for what a title cannot carry (a breaking change's migration line): at most 3 lines and 360 characters (tools/check_changelog_form.py, gated), into the EXISTING ### ... block (a second ### Added fails check-release.sh). The generator moves them into the release, adds their PR number, skips that PR's generated line.

Triage: a PR that will not merge

gh pr view <PR> --json mergeStateStatus,statusCheckRollup,reviewDecision
StateMeaningAction
Build green, still BLOCKEDrequired-check name != Buildrealign job name or ruleset 14716423
reviewDecision not APPROVED / unresolved threadreview action needed
gh pr checks prints NOTHING and mergeStateStatus=DIRTYconflict with main; GitHub runs no workflow on an unbuildable merge ref, so no CI, no auto-merge, no armingrebase onto origin/main; force-push is gated, so push a fresh branch and reopen
mergeStateStatus=UNKNOWNnot computed yetquery again; never build a mechanism on it (#1516 cost an hour)
Build red on a refactor that deleted or renamed cited codecitations gate: anchor of a file:line gone or ambiguous in a living doc (#1783; line drift alone only warns since #2231)python3 scripts/check_doc_citations.py .; drift: --fix
Test lanes reda test in no ctest entry, or a ctest -L unit test demoted vs the base (tools/check_test_lanes.py names it)register the module/test in CMakeLists.txt; a new GPU test in a gpu module needs no edit
File size redan allowlisted file past its pin ceiling (next multiple of 25)python3 tools/check_filesize.py --update

Cutting a tagged release

Version SSoT: CMakeLists.txt project(imp ... VERSION X.Y.Z). A release is its own PR.

  1. Bump project(... VERSION X.Y.Z).
  2. CHANGELOG.md: python3 tools/changelog_release.py --version X.Y.Z --since vPREV (in imp:toolchain); read the section, fix a subject that reads wrong for a stranger.
  3. docs/BENCHMARKS.md: the **Toolchain (current: \vX.Y.Z`):** line (check-release.sh` parses exactly that form).
  4. bash scripts/check-release.sh; echo $? and read the EXIT CODE (an aborted gate prints no FAIL line, #1394). Running containers: it lists them and asks Stop them for the GPU stages? [y/N], restart offered at exit; without a terminal IMP_RELEASE_STOP_CONTAINERS=yes|no (default no). Known exit-1 cause: test-spec-fidelity "skipped, card not free enough" (needs ~26 GB free after the earlier stages); run make test-spec-fidelity separately, read exit 0. check-release.sh prints only PASS make verify-fast: run make verify-fast separately for the release-note figures; bench-competitive writes /tmp/bench_competitive.tsv.
  5. Merge (squash), then git tag vX.Y.Z <sha> && git push origin vX.Y.Z.
  6. gh release create vX.Y.Z --title "vX.Y.Z: <what changed>" --notes-file <file> --verify-tag. The tag alone is not the release.

Release notes form (three headings and a footer, nothing before them; no install block, no "what imp is" paragraph, measurement conditions ride inside the numbers):

## Highlights          3-5 bullets, headline number inline, (#NNNN) for detail
## Also in here        one line each: deps, refusals, guards
## Gate                verify-fast on the tagged tree, model + quant + card named
No breaking changes. / Breaking: <what a user must change>
Full detail: CHANGELOG. N PRs since vX.Y.(Z-1).
  • Lead with what a reader can now do (a checkpoint that runs, a modality), then speed.
  • PR numbers in bullets come from git log vPREV..HEAD --oneline, not memory.
  • Titles name the change, not the anecdote: v0.25.0: Nemotron-3.5-Lightning runs; Qwen3.6-35B sees images.
  • Negative results are findings: verdict plus number.

Common mistakes

SymptomCauseFix
Release only bumped one of {CMakeLists, CHANGELOG, BENCHMARKS}bump all three

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.