docs(release-skill): warn against --ff-only and reset --hard for dev/main sync

[Wirasm]

Summary

• Problem: The release SKILL's Step 9 already uses the correct primitive (git pull origin main, which creates a regular merge commit), but doesn't explicitly warn against the two trap doors that bit us during v0.3.10. A future maintainer (or AI agent) reading the SKILL might think "the merge commit is ugly, let me clean it up" and reach for --ff-only or git reset --hard origin/main — both are wrong.
• Why it matters: We hit both traps today and it cost real time:
  • The experimental archon-release workflow used --ff-only and aborted on every release run. Workflow-level fix is in fix(release-workflow): use regular merge for dev/main sync after squash-merge #1490.
  • During v0.3.10 recovery I used git reset --hard origin/main to "clean up" the merge bubble. That severed every open PR's merge-base from its original commit and ballooned their diffs (PR fix(cli): handle --version, -V, -version, lone -v as version requests #1444 went from +80/-1 to +6626/-300). Recovered via a follow-up merge that re-attached the original commits.
• What changed: One file, 15 lines added. New > **Do NOT** callout under the existing "Important" callout in Step 9. Documents both anti-patterns and explains why each is wrong, plus the conflict-resolution gotcha (use origin/main not local main because local main is typically stale).
• What did NOT change (scope boundary): No code, no workflows, no other docs. Pure documentation update to the release SKILL.

Linked

• Companion to fix(release-workflow): use regular merge for dev/main sync after squash-merge #1490 (workflow-level fix for the same problem)
• Related bug(release-workflow): sync-dev-with-main race-clobbers CI's update-homebrew formula commit #1489 (the broader race condition with CI's update-homebrew job)

Validation

• The new content is just prose. No commands to run.
• Manually verified the line numbers and existing callout flow remain coherent.

Security Impact

None.

Compatibility / Migration

Backward compatible — documentation only.

Human Verification

I read the rendered SKILL section and the new callout reads naturally between the existing "Important" block and the GitHub Release explainer. No formatting issues.

Side Effects / Blast Radius

Single file. No code paths affected.

Rollback Plan

git revert if the new wording is wrong. The SKILL functions identically without it (just less explicit about the failure modes).

Risks and Mitigations

None of substance. Worst case: the new wording is slightly awkward; revert and rephrase.

Summary by CodeRabbit

• Documentation
  • Updated release process documentation to clarify proper branch synchronization procedures and conflict resolution guidance after tagging releases.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: b1f8f444-ec21-4c24-adc6-47555f7ea57d

📥 Commits

Reviewing files that changed from the base of the PR and between 2945f2e and b0daec2.

📒 Files selected for processing (1)

• .claude/skills/release/SKILL.md

---

📝 Walkthrough

Walkthrough

Documentation update to the release skill that clarifies git synchronization procedures after squash-merge releases. Specifies avoiding fast-forward-only pulls and hard resets when syncing dev with main, with guidance on conflict resolution for homebrew/archon.rb.

Changes

Cohort / File(s)	Summary
Release skill documentation .claude/skills/release/SKILL.md	Adds guidance forbidding --ff-only and hard resets during dev/main sync. Explains that squash-merge SHAs prevent fast-forwards. Includes recovery procedures for homebrew/archon.rb conflicts, specifying origin/main as the source reference.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Possibly related PRs

• fix(release-workflow): use regular merge for dev/main sync after squash-merge #1490: Implements the corresponding changes in the release workflow itself, replacing --ff-only with --no-edit and adding stash/checkout flow for homebrew/archon.rb, directly aligning with the documented guidance.

Poem

🐰 A pull that's fast-forward-free,
With squash-merged history,
Dev and main now sync so clean—
No resets in between!
Origin's truth, the conflict's cure, 🌿

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately and concisely describes the main change: adding documentation warnings against two specific problematic Git commands (--ff-only and reset --hard) for the dev/main sync process in the release skill.
Description check	✅ Passed	The description covers the essential sections well: it explains the problem, why it matters with concrete examples from v0.3.10, what changed, scope boundaries, validation approach, security impact, compatibility, human verification, side effects, and rollback plan. While it doesn't follow the exact template structure (UX Journey, Architecture Diagram), this is appropriate for a documentation-only change where those sections are not applicable.
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.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/release-skill-squash-merge-warnings

---

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

_{Review rate limit: 7/8 reviews remaining, refill in 7 minutes and 30 seconds.}

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