docs(skill): codify merge-resolution rules and clean-mergeable-PR requirement

[thejustinwalsh]

Summary

Dispatched agents had no codified guidance on keeping a branch mergeable or resolving divergence with main — the #90 Phase 5 merge had to be hand-driven. This folds those rules into the skill agents actually read, plus the contributor guide.

What changed

• implementing-github-issues skill (canonical + bootstrap-assets mirror, byte-identical):
  • New "Keeping the branch mergeable into main" section: enable git rerere at workstream start (resolutions replay instead of being re-earned), rebase by default, escape to a single git merge when main deeply re-architected the same code a per-commit rebase keeps re-conflicting on, the new-work-as-base resolution heuristic, and always re-verify after resolving.
  • A clean-mergeable core principle, a Phase 10c mergeability check (gh pr view --json mergeable) before gh pr ready, two red-flag rows, three quick-reference rows, and a middle-dispatch delta (headless, no human babysits the rebase).
• CLAUDE.md: expanded the "we rebase, we don't squash" note with rerere + the merge escape hatch, and added a "PR must be cleanly mergeable before ready" bullet to the PR workflow.

Why these changes

The merge strategy is a real judgment call (rebase for clean history vs. a single merge for deep interleave) with a load-bearing heuristic (new-work-as-base) that an agent won't infer on its own. rerere specifically turns a hard-won resolution into a replayable one — high leverage during multi-commit rebases. Source: the #90 merge experience.

Verification

• bun scripts/sync-skills.ts → mirror re-synced; canonical and bootstrap-assets copies diff-identical.
• Pre-commit hook confirms skills: bootstrap-assets mirror is in sync.
• Docs-only change; no code/test surface touched.

How to review

Read the new "Keeping the branch mergeable into main" section in packages/skills/implementing-github-issues/SKILL.md and the CLAUDE.md rebase note. Confirm the rebase-vs-merge decision rule and the new-work-as-base heuristic read clearly to a fresh agent.

Out of scope

• The .claude/ / .codex/ stamped skill copies are written by mm init; they pick up this content on next init/sync.

Summary by CodeRabbit

• Documentation
  • Updated contributor guidelines with enhanced Git rebase guidance and merge conflict resolution procedures.
  • Added explicit mergeability verification requirements before marking PRs as ready.
  • Expanded workflow documentation with detailed conflict-handling best practices and verification steps.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 6a4c6301-8dc1-4132-a891-89b2861720c9

📥 Commits

Reviewing files that changed from the base of the PR and between 96e098b and c7f53cd.

📒 Files selected for processing (3)

• CLAUDE.md
• packages/cli/src/bootstrap-assets/skills/implementing-github-issues/SKILL.md
• packages/skills/implementing-github-issues/SKILL.md

---

📝 Walkthrough

Walkthrough

The pull request updates contributor guidelines and autonomous skill documentation to enforce that PR branches remain cleanly mergeable into main before marking ready, adding pre-ready verification steps and comprehensive Git rebase/conflict-resolution guidance for both human contributors and headless autonomous workflows.

Changes

Mergeability Workflow Requirements

Layer / File(s)	Summary
Core mergeability prerequisite rule CLAUDE.md, packages/cli/src/bootstrap-assets/skills/implementing-github-issues/SKILL.md, packages/skills/implementing-github-issues/SKILL.md	Establishes hard requirement that PR branches must be cleanly mergeable into main before reaching ready-for-review state, framing conflict resolution as autonomous responsibility.
Pre-ready mergeability verification gate CLAUDE.md, packages/cli/src/bootstrap-assets/skills/implementing-github-issues/SKILL.md, packages/skills/implementing-github-issues/SKILL.md	Adds explicit gh pr view ... --json mergeable,mergeStateStatus check before running gh pr ready, ensuring clean merge state verification across all three documentation files.
Comprehensive mergeability maintenance section packages/cli/src/bootstrap-assets/skills/implementing-github-issues/SKILL.md, packages/skills/implementing-github-issues/SKILL.md	Introduces detailed "Keeping the branch mergeable into main" guidance: git rerere replay, default rebase against origin/main, single-merge escape hatch for deep interleaves, and re-verification workflow.
Red flags and headless dispatch reinforcement packages/cli/src/bootstrap-assets/skills/implementing-github-issues/SKILL.md, packages/skills/implementing-github-issues/SKILL.md	Updates red-flags section to prohibit deferring conflicts to humans; adds headless-dispatch reinforcement that no one will babysit rebases, requiring git rerere, sync, and confirmed mergeability before marking ready.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Suggested labels

ready-for-review

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: codifying merge-resolution rules and establishing a clean-mergeable-PR requirement, which matches the substantial documentation updates across multiple skill files and contributor guidance.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

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