/rollback

description: Create a revert PR to roll back a shipped feature or fix that caused a production incident
argument-hint: "[PR number to revert, or \"last\" for most recent deploy]"
install: extras

<!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios --> <!-- SPDX-License-Identifier: AGPL-3.0-or-later -->

/rollback — Automated Revert PR Creation

> **Skill names**: `{FORGE_SKILL_PREFIX}` is `forgedock:` (plugin install) or empty (`install.sh`), resolved once per run by `commands/work-on.md` § Skill Name Resolution. If the skill is not found under either name, STOP and report "skill not found" — never run the phase inline.

**Input**: $ARGUMENTS

**Config variables used by this command** (set in `forge.yaml`):

• `{REPO_PATH}` ← `paths.root` — project repository root
• `{DEPLOY_WORKFLOW}` ← `deploy.workflow` (optional) — GitHub Actions workflow filename for fast-track deploys (e.g., `hotfix-deploy.yml`). When absent or empty, the workflow-trigger suggestion is omitted.

You are the pipeline's emergency rollback system. When a shipped feature or fix causes production issues, this command creates a revert PR and fast-tracks it through the pipeline.

**Agent model policy**: `model: "{DEFAULT_MODEL}"` — resolved from forge.yaml `agents.default_model`, else "sonnet" (standard tier). Fallback: `model: "opus"` if rate-limited. User can override with `--model <name>`. Feature gate: pass `effort` in Task/Skill spawns only on Claude Code >= 2.1.154.

**NEVER use plan mode (EnterPlanMode)** — it breaks execution context.

---

Phase 1: Identify What to Revert

Step 1A: Parse the input

| Input | Action | |-------|--------| | PR number (e.g., `142`) | Revert that specific PR | | `last` or empty | Revert the most recent merge to `main` | | Issue number with `#` (e.g., `#55`) | Find the PR that closed this issue, revert it |

Step 1B: Resolve the target PR

# If PR number given directly
gh pr view {PR_NUMBER} --json number,title,mergeCommit,headRefName,baseRefName,body,mergedAt

# If "last" — find most recent merge to main
gh pr list --state merged --base main --limit 1 --json number,title,mergeCommit,mergedAt

# If issue number — find the PR that closed it
gh pr list --state merged --search "Closes #{ISSUE}" --limit 1 --json number,title,mergeCommit

Step 1C: Validate revert is safe

Before reverting, check:

1. **Was the PR actually merged to main?** If it's only on staging, revert from staging instead. 2. **Are there dependent PRs merged after this one?** If later PRs build on this code, a simple revert may break them.

# Check what changed in the PR
gh pr diff {PR_NUMBER} --name-only

# Check if any later PRs touched the same files
MERGE_DATE=$(gh pr view {PR_NUMBER} --json mergedAt --jq '.mergedAt')
gh pr list --state merged --base main --json number,title,mergedAt,files \
  --jq ".[] | select(.mergedAt > \"$MERGE_DATE\") | {number, title}"

If dependent PRs exist, warn the user:

⚠️ PRs merged AFTER #{PR_NUMBER} that touch the same files:
- #{LATER_PR} — {title}

A simple revert may break these. Options:
1. Revert all dependent PRs together (risky)
2. Create a targeted fix instead of a full revert
3. Proceed with revert anyway (you'll need to fix conflicts)

Which approach? (Reply or press enter for option 1)

---

Phase 2: Create the Revert

Step 2A: Create a revert branch

cd {REPO_PATH}
git fetch origin main
git worktree add ../revert-pr-{PR_NUMBER} -b revert/pr-{PR_NUMBER} origin/main

cd ../revert-pr-{PR_NUMBER}

Step 2B: Execute the revert

# Get the merge commit SHA
MERGE_SHA=$(gh pr view {PR_NUMBER} --json mergeCommit --jq '.mergeCommit.oid')

# Revert the merge commit (use -m 1 for merge commits to select the mainline parent)
git revert -m 1 $MERGE_SHA --no-edit

If the revert has conflicts:

# Show conflicts
git diff --name-only --diff-filter=U

# Report to user
echo "Revert has conflicts in these files:"
git diff --name-only --diff-filter=U
echo ""
echo "This usually means later changes depend on the reverted PR."
echo "Manual resolution needed — opening conflicted files for review."

If conflicts cannot be auto-resolved, report to user and STOP.

Step 2C: Verify the revert compiles

Read `forge.yaml → verification.commands` for project-specific tool commands:

# Python compile check (always runs — no config needed)
for f in {reverted_python_files}; do
    python3 -m py_compile "$f" 2>&1
done

# Python format check (config-driven)
PYTHON_FORMAT=$(yq '.verification.commands.python.format // ""' forge.yaml 2>/dev/null || echo '')
if [ -n "$PYTHON_FORMAT" ]; then
    eval "$PYTHON_FORMAT" 2>&1 | head -20
else
    echo "SKIPPED — python.format not configured in verification.commands"
fi

# TypeScript typecheck (config-driven)
TS_TYPECHECK=$(yq '.verification.commands.typescript.typecheck // ""' forge.yaml 2>/dev/null || echo '')
if [ -n "$TS_TYPECHECK" ]; then
    eval "$TS_TYPECHECK" 2>&1 | head -20
else
    echo "SKIPPED — typescript.typecheck not configured in verification.commands"
fi

---

Phase 3: Create the Revert PR

Step 3A: Push and create PR

git push origin revert/pr-{PR_NUMBER}

gh pr create --base main --title "Revert: #{PR_NUMBER} — {original_title}" --body "$(cat <<'PR_EOF'
## Revert

Reverts #{PR_NUMBER} ({original_title}).

**Reason**: {user-provided reason or "Production incident — rollback requested"}

**Original PR**: #{PR_NUMBER}
**Merge commit**: {MERGE_SHA}

## What This Reverts

{List of files changed, from the original PR}

## Verification

- [ ] Revert compiles cleanly
- [ ] No dependent PRs broken
- [ ] Production incident should resolve after deploy
PR_EOF
)"

Step 3B: Fast-track decision

**If this is a P0 incident** (user said "urgent", "P0", "production down", or similar):

• Skip the full review — revert PRs are low-risk (they restore known-good state)
• Merge immediately:

gh pr merge {REVERT_PR} --merge