levy-street/world-of-claudecraft / .claude/skills/release-merge-audit
release-merge-audit
VerifiedRelease-merge audit
A release merge into a long-lived feature branch routinely lands surprises that neither CI nor
the merge conflict markers surface. This audit has paid for itself four times on
feature/api-re-architecture alone:
- A release hotfix changed a LEGACY route arm the branch had already migrated, so the migrated handler silently diverged (parity break with no conflict).
- A release refactor added a parameter to a helper the branch receives BY INJECTION
(
passesTurnstilegained a secret argument); the un-re-bound injection site silently disabled the gate. - A release added 12 routes the branch's surface inventory did not know about, 6 of them invisible to the parity corpus.
- A release hotfix pre-landed half of some planned work (the market realm-scoping) with a different mechanism than the branch's plan assumed, invalidating the plan's premise.
Run every step; each targets one of those failure classes. No em dashes or emojis in anything you write.
Step 1: identify the merge and its delta
The merge commit is the argument if given, else the most recent RELEASE merge. Both subject
forms occur in this history: the plain form (Merge branch 'release/v0.23.0' ...) and the far
more common remote-tracking form (Merge remote-tracking branch 'origin/release/v0.25.0' ...,
also with upstream/ or up/). Match both:
git log --merges -1 --format='%H %s' \
--grep="branch '\(origin/\|upstream/\|up/\)\?release/" HEAD
Print %s and read it: hand-written subjects (e.g. merge: resync with release/v0.23.0) do
not match this grep, and a bare git log --merges -1 can grab an unrelated merge, e.g. a
main-merge, so when in doubt pass the commit explicitly. The audit
assumes a true two-parent merge commit; a squash-merged release has no ^2, so pass the
commit explicitly and treat its own diff as the incoming delta. The incoming delta (what the
release brought, relative to the branch):
git diff --name-only <merge>^1..<merge>
^1 is the branch-side parent. Also record the merged release ref (git log -1 <merge>^2).
Step 2: intersect with branch-owned surfaces
Compute the files the BRANCH owns (changed on the branch before the merge):
git diff --name-only "$(git merge-base <merge>^1 main)"..<merge>^1
Intersect with Step 1's list. Every overlapping file is a manual-read item: the release and the
branch both changed it, and the merge resolution may have quietly dropped either side's intent.
For each overlap, read the merged result against BOTH parents (git show <merge>^1:<file>,
git show <merge>^2:<file>) and confirm no side's behavior was lost. A base-merge can silently
revert a feature in one hunk.
Step 3: legacy-arm divergence (migrated surfaces)
For each route or handler the branch has MIGRATED that the release touched: did the release change land only on the legacy arm? If so, mirror it into the migrated handler and add a parity case in the same change. On the API pipeline, remember a knownDeviation masks its WHOLE path, so re-pin corpus fixtures via captureBothModes rather than widening a deviation.
Step 4: new endpoints and inventory rows
List any route, WS command, or endpoint the release ADDED (grep the delta for route tables,
dispatch cases, app./registry additions). Each needs: an owner on the branch's architecture
(for the pipeline: a RouteDef, router-owned AND legacy-served during rollback retention), and a
row in the surface inventory / parity corpus. A corpus-invisible route is unaudited by
definition.
Step 5: injected and re-bound helpers
For each function in the delta whose signature or closure changed: find every place the branch passes it BY INJECTION (boot wiring, configure*Runtime calls, DI seams) and confirm the injection site was re-bound with the new shape. A stale binding compiles fine and silently skips the new behavior.
Step 6: planning-doc premise re-check
Locate the branch's planning docs first: they usually live under docs/<epic>/ (for the API
pipeline, docs/api-pipeline/), and files like state.md/progress.md name the work in
flight. Re-read whichever doc describes the ACTIVE work plus those two files. Did the merge
land code they assume absent, or implement a planned mechanism a different way? If yes,
correct the premise in the docs BEFORE implementing against it, and note the correction in
memory.
Step 7: report and fix
Produce a short report: overlaps read (Step 2), divergences mirrored (Step 3), inventory rows
added (Step 4), bindings re-checked (Step 5), premises corrected (Step 6), each with file:line.
Apply the fixes in the same change with a parity/regression test per divergence, then run the
targeted suites plus npx tsc --noEmit (or npm run gate if the merge was large).
Two recurring traps to check in the same pass:
- i18n merge mechanics. The aggregate baseline and status summary are no longer
committed, so a merge where both sides changed catalog keys only needs
npm run i18n:gento reconcile the committed line-item slices. Never re-baseline by hand; that historical trap applies only to branches predating the baseline's removal. - Stale db-mock export lists. A release-authored test that drives GameServer can mock
../server/dbwith the RELEASE tree's export list, so a db function the BRANCH added throws "No X export is defined on the mock" only on the merged tree; neither parent carries the fix and only the full gate catches it. After any merge bringing newvi.mock('../server/db')sites, diff each mock's keys against whatserver/game.tsimports on the branch and mirror the branch's canonical mock shape (template:tests/character_lease_game.test.ts).
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |