feat(skill): Add merging branches by intent skill

[ajcasagrande]

Summary

• Add the merging-branches-by-intent skill under .agents/skills
• Provides the intent-preserving workflow for resolving non-trivial branch merges

How it works

• Starts from the merge base and has parallel agents produce intent reports for each branch: what changed, why, invariants, blast radius, and refactor/rename risks.
• Builds a conflict risk map before merging, then resolves each conflict by preserving both branches' intent rather than choosing one diff.
• Runs a post-merge semantic sweep for non-textual hazards like refactor-vs-feature gaps, stale imports/signatures, missed registry/config extensions, and cross-cutting conventions.
• Requires verification that build/tests pass and that every recorded branch intent is still satisfied before committing the merge.

Test plan

• Verified copied SKILL.md hash matches existing source skill
• Pre-commit hooks passed during commit

🤖 Generated with Claude Code

[coderabbitai]

Warning

Rate limit exceeded

@ajcasagrande has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 19 minutes and 22 seconds before requesting another review.

You’ve run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: e01ebfb6-66d8-421c-8479-45ba459dce63

📥 Commits

Reviewing files that changed from the base of the PR and between bb6f421 and e4a2961.

📒 Files selected for processing (1)

• .agents/skills/merging-branches-by-intent/SKILL.md

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

Try out this PR

Quick install:

pip install --upgrade --force-reinstall git+https://github.com/ai-dynamo/aiperf.git@e4a2961a3aba821dc417a076f594e2753d7587ad

Recommended with virtual environment (using uv):

uv venv --python 3.12 && source .venv/bin/activate
uv pip install --upgrade --force-reinstall git+https://github.com/ai-dynamo/aiperf.git@e4a2961a3aba821dc417a076f594e2753d7587ad

---

Last updated for commit: e4a2961 • Browse code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[FrankD412]

Knit: Some folks seem to think bold and caps help Claude/Codex adhere. For directives like Do not guess. might be worth trying *DO NOT GUESS.?

Just a thought, if this has been working for you then feel free to disregard.

[matthewkotila]

Knit

[matthewkotila]

Consider adding a seventh risk class for intent-level conflicts that don't share a symbol or a region. "Semantic drift" above is narrowly scoped to same-name-different-contract — it catches symbol-level collisions but not cases where one branch's change invalidates an invariant the other branch's design depends on, even when no file overlaps.

Concrete examples:

• Branch A removes the retry middleware because downstream calls were made idempotent. Branch B adds a configurable retry policy to a handler that relied on the old non-idempotent semantics. No textual conflict; no shared symbol; B's feature now sits on top of an invariant A just deleted.
• Branch A introduces strict-typed plugin contracts via a registry. Branch B adds a duck-typed dynamic plugin path. Both merge cleanly; the merged system now has two incompatible plugin philosophies.
• Branch A adds a request-boundary cache. Branch B adds bespoke memoization in one handler for the same reason. Result is either dead weight or double-caching.
• Branch A enforces validation in the Pydantic model. Branch B adds the same check in a service-layer guard. Two sources of truth, no rule for which wins.

Suggested addition to the list here:

- **Invariant conflict / intent collision** — one branch's change invalidates, duplicates, or obsoletes an invariant the other branch's intent depends on, even when no textual conflict and no shared symbol exists. Detection requires cross-checking each branch's invariants (Step 2) against the *other* branch's diff, not against the merged tree.

And a matching rule-of-thumb under "Resolve by intent" (near the semantic-drift bullet), since detection is different from semantic drift:

- **Invariant conflict:** the merge is textually clean but the design premises don't compose. Do not paper over with a synthesis edit — escalate to the humans who wrote each side and decide which premise the merged system holds. The fix is often a follow-up commit that retires one side, not a conflict resolution.

Rationale: the intent-agent prompt already asks for INVARIANTS the change assumes or establishes, so the raw material is captured — but Step 3's risk map currently has no bucket to file invariant collisions into, so they tend to fall through. Naming the class makes them explicit and gives the sweep agent (Step 6) a question to ask: "for each invariant on branch A, does any change on branch B violate or obsolete it, and vice versa?"