Revert

Revert

Purpose: Safely rollback changes using git revert Phases: Identify -> Assess -> Revert -> Validate -> Commit Usage: /revert [target] [scope flags]

Constraints

• Never force push after revert without explicit approval
• Never revert without user confirmation
• Never leave unresolved conflicts
• Never use git reset --hard -- use git revert instead
• Never revert shared history without team coordination
• Show what will be reverted before applying
• User confirmation of target required
• User approval of plan required
• Validation after revert required
• User confirmation before commit required
• Document reason for revert when provided
• Create follow-up todo if revert is temporary
• Notify team of significant reverts
• Consider PR for reverts on shared branches

Note: Command examples use npm as default. Adapt to the project's package manager per ai-assistant-protocol — Project Commands.

Target Options

Scope Flags

Examples:

/revert                            # Revert last commit
/revert HEAD~3                     # Revert last 3 commits
/revert abc123                     # Revert specific commit
/revert --pr=456                   # Revert PR #456
/revert abc123 --reason="broke prod"  # Revert with reason
/revert HEAD --dry-run             # Preview revert

Workflow

Phase 1: Identify

Goal: Parse target and show what will be reverted

Step 1.1: Parse Target

# Get current state
git branch --show-current
git log --oneline -10

If the target commit does not exist: Report "Target commit not found — verify the SHA or reference" and exit.

If the target commit has already been reverted (a "Revert [message]" commit exists for it): Report "This commit appears to have already been reverted" and exit.

Parse target from input:

## Revert Target

| Parameter | Value |
|-----------|-------|
| Target | `[HEAD / sha / range]` |
| Commits | N commit(s) |
| Reason | [if provided] |
| Mode | [normal / dry-run / no-commit] |

Step 1.2: Show Commits to Revert

# For single commit
git show --stat [sha]

# For range
git log --oneline [range]

# For PR
gh pr view [number] --json commits

Display commits: See references/revert-display-templates.md for full display format.

Step 1.3: Show What Will Change

# Show combined diff of commits being reverted
git diff [sha]^..[sha]

Display changes: See references/revert-display-templates.md for full display format.

Step 1.4: Confirm Target

Display confirmation prompt: See references/revert-display-templates.md for full display format.

GATE: User must confirm target.

Phase 2: Assess

Goal: Evaluate impact and conflict risk

Step 2.1: Check if Target is a Merge Commit

# Inspect the commit object to count parent lines
git cat-file -p [sha]

If the output contains 2 or more parent lines, this is a merge commit.

When a merge commit is detected:

1. Explain the parent options:

> **ACTION REQUIRED:**
> This is a merge commit. Which parent should be the mainline?
>
> - `1` - Keep changes from main branch (revert the merged feature)
> - `2` - Keep changes from feature branch (revert main-side changes)
>
> Parent 1: `[parent-1-sha]` ([branch name if identifiable])
> Parent 2: `[parent-2-sha]` ([branch name if identifiable])
>
> **Usually you want option 1 to revert a merged feature.**
>
> **Which parent?**

2. Wait for user selection before proceeding.
3. Use git revert -m <parent-number> [sha] in Phase 3 instead of plain git revert [sha].

GATE: If merge commit, user must select parent before continuing.

Step 2.2: Check for Dependent Changes

# Check if any commits after target depend on it
git log --oneline [sha]..HEAD

# Check for merge commits that include target
git log --oneline --merges [sha]..HEAD

If dependent commits found: See references/revert-display-templates.md for warning display format.

Wait for decision.

Step 2.2: Assess Conflict Risk

# Check if files were modified since target
git diff --name-only [sha] HEAD

If conflicts likely: See references/revert-display-templates.md for conflict risk display format.

Step 2.3: Present Revert Plan

## Revert Plan

**Target:** `[sha]` - "[message]"

**Approach:**
- Revert method: `git revert [sha]`
- Conflict risk: [Low / Medium / High]
- Dependent commits: [None / List]

**Expected outcome:**
- Changes from `[sha]` will be undone
- New commit will be created: "Revert [message]"
- History preserved (original commit visible)

**Approve revert?** (yes / modify / abort)

GATE: User must approve plan.

Phase 3: Revert

Goal: Apply the revert and handle any conflicts

Step 3.1: Apply Revert

If dry-run mode:

git revert --no-commit [sha]
git diff --staged
git reset HEAD  # Undo the staged revert

## Dry Run Results

**Would revert:**
- Commit: `[sha]`
- Files changed: N

**Changes preview:**
[diff output]

**No changes made.** Run without `--dry-run` to apply.

Otherwise:

# For single commit
git revert [sha] --no-commit

# For multiple commits (reverse order)
git revert [sha1] [sha2] [sha3] --no-commit

# For range
git revert [older]..[newer] --no-commit

Step 3.2: Handle Conflicts

If conflicts occur: See references/revert-display-templates.md for conflict resolution display format.

Wait for decision.

If resolving:

# Show conflict markers
git diff --name-only --diff-filter=U

For each conflicted file: See references/revert-display-templates.md for per-file conflict display format.

After resolution:

git add [resolved-files]

Step 3.3: Review Staged Revert

## Staged Revert

**Files to be reverted:**
| File | Status |
|------|--------|
| `src/feature.ts` | Reverted |
| `tests/feature.spec.ts` | Reverted |

**Conflicts resolved:** [Yes/No/N/A]

Ready to validate?

Phase 4: Validate

Goal: Confirm the codebase is healthy after revert

Step 4.1: Run Validation

# Type check
npm run typecheck

# Lint
npm run lint

# Tests (scoped to affected areas)
npm run test -- [affected-patterns]

Step 4.2: Validation Report

## Validation After Revert

| Check | Status | Details |
|-------|--------|---------|
| Type check | Pass / Fail | [details] |
| Lint | Pass / Fail | [details] |
| Tests | Pass / Fail | X passed, Y failed |

**Validation passed?** [Yes/No]

If failures:

> **WARNING:**
> Validation failed after revert.
>
> **Issues:**
> - [list issues]
>
> **This likely means:**
> - Later code depends on the reverted changes
> - Additional fixes needed after revert
>
> **Options:**
> 1. Fix issues and continue with revert
> 2. Abort revert (reset staged changes)
> 3. Create todo for fixes and proceed
>
> **How to proceed?**

Wait for decision.

Phase 5: Commit

Goal: Finalize the revert commit

Step 5.1: Prepare Commit Message

## Revert Commit

**Default message:**

Revert "[original commit message]"

This reverts commit [sha].

[Reason if provided]

**Customize message?** (yes / use default)

Step 5.2: Confirm Commit

## Ready to Commit Revert

**Reverting:** `[sha]` - "[message]"
**Files changed:** N
**Reason:** [reason if provided]

**Commit message:**

Revert "feat: add feature"

This reverts commit abc123.

Reason: Feature caused production issues.

**Create revert commit?** (yes / edit message / abort)

GATE: Never commit without explicit "yes".

git commit -m "Revert \"[original message]\"

This reverts commit [sha].

[Reason]"

Step 5.3: Completion

## Revert Complete

| Item | Value |
|------|-------|
| Reverted commit | `[sha]` |
| Revert commit | `[new-sha]` |
| Files changed | N |

**Next steps:**
- Push to remote: `git push origin [branch]`
- Create PR if needed
- Deploy if urgent

**Note:** Original commit `[sha]` remains in history.
To undo this revert: `git revert [new-sha]`

Acceptance Tests

Additional References

• Special Cases & Recovery Options -- Merge commit reverts, PR reverts, partial reverts, and recovery procedures
• Display Templates -- Full markdown display templates for user-facing output in each phase

Converted and distributed by TomeVault — claim your Tome and manage your conversions.