| name | rollback |
| description | Use when the user wants to undo a broken commit, push, or PR — triggered by /rollback, 'rollback', 'revert that', 'undo last commit', 'undo the push', 'restore branch'. Auto-detects the rollback target from current state (last commit / pushed range / open PR / merged PR) and chooses the safest reversal path. Never destroys history without explicit confirmation. |
Rollback — Recovery Workflow
When to Use
- User says "/rollback", "rollback", "revert", "undo", "restore"
- A broken commit / merged bad PR / pushed defect / corrupted branch needs reverting
Auto-Detect Target
No gh? Use the equivalent mcp__github__* tool for every gh call below — see agent_docs/mcp_catalog.md → the github row.
git rev-parse --abbrev-ref HEAD
git status --porcelain
git log -1 --pretty='%H %s'
git log @{u}..HEAD --oneline 2>/dev/null
git log HEAD..@{u} --oneline 2>/dev/null
gh pr list --head $(git rev-parse --abbrev-ref HEAD) --json number,state 2>/dev/null
Decision matrix:
| State | Action |
|---|
| Uncommitted local changes only | Phase A (discard working tree, opt-in) |
| Local commits, not pushed | Phase B (reset back N commits) |
| Pushed commits on feature branch | Phase C (revert + push, or force-with-lease — explicit) |
| Pushed to main + bad commit on top | Phase D (revert + push) |
| Merged PR causing breakage | Phase E (revert PR via gh) |
| Branch deleted by mistake | Phase F (restore from reflog / origin) |
Always print the detected state and proposed action before executing, then wait for confirmation.
Phase A — Discard uncommitted changes
User must explicitly confirm. Loses local work.
git diff --stat
git restore --staged .
git restore .
Phase B — Reset local-only commits
git log @{u}..HEAD --oneline
git reset --hard HEAD~N
Phase C — Revert pushed commits on feature branch
Default: revert (preserves history). Force-push only on explicit user request.
git revert --no-edit HEAD~N..HEAD
git push
Phase D — Revert on main
Always use git revert on main. Never git reset --hard on main without explicit user override.
git revert --no-edit <bad-sha>
git push origin main
If revert produces a conflict → stop, ask user to resolve manually.
Phase E — Revert merged PR
gh has no pr revert subcommand — build the revert PR manually. A revert PR is preferred over a direct push to main.
PR=<number>
gh pr view "$PR" --json mergeCommit,baseRefName,headRefName
git checkout main && git pull
git checkout -b revert-pr-$PR
git revert -m 1 <merge-commit-sha>
git push -u origin revert-pr-$PR
gh pr create --title "Revert PR #$PR" --body "Reverts #$PR — <reason>"
gh pr comment "$PR" --body "Reverted via #<new-pr-number> — <reason>"
Phase F — Restore deleted branch
git reflog | head -20
git branch <name> <sha>
git push -u origin <name>
Hard Rules
- Never
git reset --hard on main. Always revert.
- Never
git push --force on main. Default is revert + new commit.
- Never delete a branch as part of rollback — only restore / revert.
- Always print a dry-run diff of what the rollback will change before executing.
- Always confirm with the user before destructive ops (
reset --hard, force-push, branch delete).
- Checks must pass after rollback. If the rollback itself breaks the build, stop and surface.
After Rollback
- Run
compileall + Qt smoke per CLAUDE.md.
- Comment on the original PR / issue explaining the rollback (English, short).
- Recommend a follow-up: open a new branch, fix the root cause, do not just re-apply.
Report
↩️ Rollback complete
Phase: <A/B/C/D/E/F>
Reverted: <commits or PR number>
Branch: <branch>
Checks: <pass/fail>
Next: <link to follow-up branch or issue, if applicable>
If failed:
❌ Rollback halted
Reason: <conflict / check failure / missing reflog entry>
State: <what's currently true on disk + remote>
Next steps: <concrete commands the user can run>
