docs(integration): add merge log/summary formats and an integration-branch skill [skip-ci] - #547
Merged
Merged
Conversation
RonenMars
force-pushed
the
docs/integration-log-formats
branch
from
August 12, 2026 18:19
20b8f7f to
e225837
Compare
…ranch skill [skip-ci] The log format is derived from docs/landing/2026-08-01-rehearsal-notes.md and the summary format from docs/postmortems/2026-07-22-merge-all-open-prs-report.md, which are the two most structured records of past integration runs. Adds what those logs were missing: a baseline measurement of main before any merge, environment provenance, a semantic-conflict section recorded even when clean, judgment calls with the discarded side, a per-PR diff-scope check after rebase, deferrals with an owner, rollback commands, and a gaps-in-this-log section. The skill defaults to every open PR, accepts a range or explicit list, and can additionally merge named local/remote branches with no PR. It cuts from the earliest PR branch, rebases onto main, merges one PR at a time with a log entry per merge, and writes the summary at the end. It never pushes to main and never lands PRs. The run is one of three flows, chosen up front and differing only in what they may write. A rehearsal keeps origin read-only and produces the conflict ledger and command sequence that make the real run mechanical. A real run replaying that rehearsal re-verifies every SHA first, because a moved PR head invalidates the ledger for that PR. A real run with no rehearsal is gated behind an explicit warning and approval: resolutions are made once with no ledger, force-pushing a rebased PR head rewrites a branch CI and review threads point at, children do not reliably auto-restack, and none of it is undoable from the client. The default is rehearsal first, then the replay, and the two are never chained automatically — writing to origin is a separate consent. Every PR after the earliest one, and every extra non-PR branch, rebases onto the current integration tip rather than onto main, so conflicts surface per-commit with the PR's own context and the merge is clean. Only the earliest PR rebases onto main, when the branch is cut. The rebase stays local unless the PR head is deliberately force-pushed, which is a write under the flow gate.
RonenMars
force-pushed
the
docs/integration-log-formats
branch
from
August 12, 2026 18:31
e225837 to
b5419a8
Compare
Claude Code discovers every .claude/skills/<name>/SKILL.md automatically, so nothing registers a skill and CLAUDE.md must not be edited to make one visible. The README says that once, lists the seven current skills with when to use each, and records the conventions a new skill should follow — the description is the trigger and needs the phrasings a user would actually say, the body is executed so traps belong inline at the step that hits them.
…skip-ci] Before taking any member of the set, the skill now checks whether the head branch exists on origin and, if it does, whether its CI is green — counting check names rather than conclusions, since a DIRTY PR has no merge ref and its real suite never ran. A red or never-run CI informs the user without asking and the run continues, then the skill looks for a fix among the other PRs and branches in the set; finding one turns the pair into a forced-order constraint rather than a blocker. Only when nothing in the set fixes it does the run stop and ask, with options rather than a bare question. A user who says up front that red CI must not stop the run removes the halt, not the check — the check still runs and still gets logged, so the run can tell which failures it inherited.
…early [skip-ci] For a few seconds after a push the rollup still carries only the previous run's stale contexts, which is indistinguishable from a suite that never ran. Confirm the run exists with gh run list before concluding anything from a short list of check names.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds two standardized document formats for integration-branch work, plus a skill that drives the merge and produces both.
What is here
docs/integration/log-format.md— the live merge log, appended after every action during the run.docs/integration/summary-format.md— the end-of-run summary, derived from the log..claude/skills/integration-branch/SKILL.md— the skill that runs the integration and writes both documents.Where the formats come from
The log format is derived from
docs/landing/2026-08-01-rehearsal-notes.md, the most structured record of a past run: provenance and per-checkpoint SHA tables, a numbered conflict ledger that classifies each resolution as mechanical or judgment, numbered detours, and a closing section auditing the log's own gaps.The summary format is derived from
docs/postmortems/2026-07-22-merge-all-open-prs-report.md, whose order table then conflicts then problems-git-did-not-flag then obstacles then verification then takeaways shape is the right skeleton for a document read instead of the log.What those logs were missing, and is now in the format
mainbefore anything merges — the repo's own notes recordmainbeing red and later counts being misattributed to the merge.npm civersus a copiednode_modules, host load.The skill
Defaults to every open PR; accepts a range or an explicit list; can additionally merge named local or remote branches that have no PR.
It cuts from the earliest PR's branch, rebases onto
main, then merges one PR at a time, running lint and tests and appending a log entry after each merge.Stacked PRs and forced-order constraints are detected and recorded before merging, because chronological order is only the default.
It ends with a coverage gate and the summary document.
It never pushes to
mainand never lands PRs — that stays a separate, explicitly requested operation.Verification
Documentation and skill markdown only; no source, workflow, fixture, schema or migration is touched, so the title carries
[skip-ci].