Smart Revert

Git-aware intelligent revert system for reverting logical work units (tracks, phases, tasks) while handling complex Git histories.

When to Use

Reverting completed tasks that need to be redone
Rolling back entire phases that didn't meet requirements
Undoing track changes after failed review
Recovering from implementation mistakes
Cleaning up after interrupted work

Core Concepts

Logical vs Physical Revert

| Type | Description | Example | | ------------ | ----------------------------------------------- | ----------------------- | | Logical | Revert a track/phase/task as defined in plan.md | "Revert Task 2.1" | | Physical | Revert specific Git commits | "Revert commit abc1234" |

This skill bridges the gap: given a logical target, it finds all physical commits.

4-Phase Protocol

Phase 1: Interactive Target Selection

Check for explicit target: Did user specify what to revert?
If no target: Present guided menu of candidates:
- First: In-progress items ([~])
- Fallback: Recently completed items ([x])
Confirm intent: Verify understanding before proceeding

Menu Format:

I found the following items to potentially revert:

Track: user-auth_20250115
  1) [Phase] Phase 2: Core Logic
  2) [Task] Task 2.1: Implement validation

3) A different Track, Task, or Phase

Which would you like to revert?

Phase 2: Git Reconciliation

Goal: Find ALL commits related to the logical unit.

Find implementation commits:
- Extract SHAs from plan.md ([x] Task: Description \abc1234``)
- Handle "ghost commits" (rebased/squashed)
Find plan-update commits:
- For each implementation SHA, find the following plan.md update
Find track creation commit (if reverting entire track):
- Search git log for when track entry was added to tracks.md

Handling Ghost Commits:

SHA abc1234 from plan.md not found in git history.
This may have been rewritten by rebase/squash.

Searching for similar commits...
Found: def5678 "feat(user): implement validation"

Is this the correct commit? (yes/no)

Phase 3: Execution Plan Confirmation

Present clear summary before any action:

## Revert Execution Plan

**Target**: Task 2.1 "Implement user validation"
**Commits to Revert**: 2

1. `abc1234` - "feat(user): implement validation"
2. `def5678` - "conductor(plan): mark task 2.1 complete"

**Action**: Run `git revert --no-edit` on each commit (newest first)

Do you want to proceed?
A) Yes - execute the revert
B) No - cancel and review

Phase 4: Execution & Verification

Execute reverts (newest to oldest):
```
git revert --no-edit <sha>
```

Handle conflicts: If conflict occurs, provide guidance:

Merge conflict detected. Please resolve manually:
1. Edit conflicted files
2. Run: git add .
3. Run: git revert --continue

Verify plan state: Re-read plan.md to confirm status reset
Announce completion: Confirm revert succeeded

Commit Identification Strategies

Finding Implementation Commits

# Extract SHA from plan.md
grep -oP '\[x\].*`\K[a-f0-9]{7}' plan.md

# Verify SHA exists
git cat-file -t <sha>

Finding Plan Update Commits

# Find commits that modified plan.md after implementation
git log --oneline -- path/to/plan.md | head -5

Handling Rebased History

# Search by commit message similarity
git log --oneline --all | grep -i "implement validation"

# Search by file changes
git log --oneline --all -- src/models/user.py

Finding Track Creation

# Find when track was added to registry
git log -p -- conductor/tracks.md | grep -B5 "Track: user-auth"

Safety Features

Multiple Confirmation Gates

| Gate | Purpose | When | | --------------------- | ----------------------------- | ------------------------- | | Target confirmation | Verify correct item selected | After selection | | Execution plan review | Show exactly what will happen | Before any git operation | | Final go/no-go | Last chance to cancel | Immediately before revert |

Conflict Handling

If git revert fails:

Do NOT force or continue automatically
Explain what happened
Provide manual resolution steps
Offer to help after user resolves

Post-Revert Verification

Always verify the plan file reflects the revert:

Before: [x] Task 2.1: Implement validation `abc1234`
After: [ ] Task 2.1: Implement validation

If plan state is inconsistent, offer to fix it.

Example Scenarios

Scenario 1: Revert Single Task

User: "Revert the last task I completed"

Agent:
1. Read plan.md, find most recent [x] task
2. Extract SHA: abc1234
3. Find plan-update commit: def5678
4. Present: "Revert Task 2.1? Will undo abc1234, def5678"
5. User confirms
6. Execute: git revert --no-edit def5678 && git revert --no-edit abc1234
7. Verify plan.md shows [ ] for task
8. Report success

Scenario 2: Revert Entire Phase

User: "/smart-revert phase 2"

Agent:
1. Find all tasks in Phase 2 with [x] status
2. Collect all implementation SHAs
3. Collect all plan-update SHAs
4. Find phase checkpoint SHA
5. Present comprehensive plan
6. User confirms
7. Execute reverts in reverse order
8. Verify all Phase 2 tasks show [ ]
9. Report success

Scenario 3: Handle Ghost Commit

Agent: "Looking for SHA abc1234..."
Agent: "SHA not found. Checking for rebased commits..."
Agent: "Found similar commit def5678: 'feat(user): validation'"
Agent: "Is def5678 the correct replacement? (yes/no)"
User: "yes"
Agent: [continues with def5678]

Integration Points

With track-management

Read plan.md and tracks.md to understand work structure.

With workflow-patterns

Follow established commit conventions when creating revert commits.

With context-driven-development

Update context files if revert affects product features.

Anti-Patterns

Do NOT:

Revert without confirmation
Ignore ghost commits (fail silently)
Leave plan.md in inconsistent state
Force-push after revert
Revert merge commits without special handling

Do:

Always verify target before action
Handle rewritten history gracefully
Verify plan state after revert
Provide clear conflict resolution guidance
Document what was reverted in commit message

Integration with Git Notes (Enhanced - Phase 1.5)

Logical Unit Identification

Instead of asking "Which commits?", ask "Which feature/bug?"

Old Workflow:

User: "Revert commit abc123"
Agent: Runs git revert abc123

New Workflow (Git Notes-Based):

User: "Revert the dark mode feature"
Agent:
- Search git notes for "dark mode" or feature ID
- Find all related commits via logical-unit-tracker.cjs
- Show: "Revert these commits? [A, B, C]"
- User: "Yes"
- Execute: git revert -n C B A (reverse order)
- Result: Feature cleanly reverted

How It Works

Find Unit: Invoke logical-unit-tracker.cjs to group commits by task
Show Options: List tasks with commit count
- Task #6: Dark Mode (2 commits)
- Task #7: Button Refactor (3 commits)
Confirm: User selects task to revert
Check Dependencies: Warn if other tasks depend on this
Execute: Revert all commits for task (reverse order)
Verify: Show revert result and update git notes

Logical Unit Tracker API

const logicalUnitTracker = require('./.claude/lib/utils/logical-unit-tracker.cjs');

// Group commits by task ID from git notes
const groups = await logicalUnitTracker.groupByTask(repoPath, 'HEAD~10..HEAD');
// Returns: { "6": [{hash, message, note}], "7": [{...}] }

// Find dependencies
const deps = await logicalUnitTracker.findDependencies(repoPath, '7', { transitive: true });
// Returns: ["6"] if Task #7 depends on Task #6

// Check safety before reverting
const safety = await logicalUnitTracker.checkRevertSafety(repoPath, '6');
// Returns: { safe: boolean, blockers: [], warning: string }

// Execute revert for entire task
const result = await logicalUnitTracker.revertTask(repoPath, '6');
// Returns: { success: boolean, conflicts: boolean, message: string }

// Find task by name
const tasks = await logicalUnitTracker.findTaskByName(repoPath, 'Dark Mode');
// Returns: ["6"] if Task #6 has "Dark Mode" in notes

Example Usage

Revert by Feature Name:

User: "Can we revert the dark mode feature?"

smart-revert workflow:
1. Find tasks by name: logicalUnitTracker.findTaskByName(repo, 'dark mode')
2. Found Task #6 with 2 commits
3. Check safety: logicalUnitTracker.checkRevertSafety(repo, '6')
4. Show plan:
   - Revert "Add dark mode toggle" (abc123)
   - Revert "Update CSS for dark mode" (def456)
5. User confirms
6. Execute: logicalUnitTracker.revertTask(repo, '6')
7. Result: "Dark mode reverted. 2 commits reverted successfully."

Revert by Task ID:

User: "Revert task #6"

smart-revert workflow:
1. Group commits: logicalUnitTracker.groupByTask(repo, 'HEAD')
2. Find Task #6 commits
3. Check dependencies: findDependencies(repo, '6')
4. No dependencies found
5. Execute revert in reverse order
6. Verify success

Dependency Warning:

User: "Revert the button refactor"

smart-revert workflow:
1. Find Task #7 (Button Refactor)
2. Check safety: checkRevertSafety(repo, '7')
3. Warning: "Task #8 (Modal) depends on Task #7"
4. Offer options:
   - Revert both #7 and #8
   - Don't revert
   - Force revert (handle conflicts manually)
5. User selects option
6. Execute based on choice

Benefits

For Users:

Feature-level revert (not commit-level)
No need to remember commit hashes
Automatic correct order (reverse chronological)
Dependency checking prevents breaking other features

For Safety:

Git notes provide context for every commit
Reverse order prevents conflicts
Verification before execution
Audit trail preserved in git notes

For Automation:

Integrates with git-notes-audit hook (automatic note creation)
Works with existing conductor workflow
No manual note maintenance required

Integration with git-notes-audit Hook

The git-notes-audit.cjs hook automatically creates git notes for every commit:

{
  "taskId": "6",
  "timestamp": "2026-01-29T10:30:00Z",
  "author": "user@example.com",
  "metadata": {
    "phase": "implementation",
    "track": "user-auth_20250115"
  }
}

This enables:

Automatic task grouping (no manual note management)
Dependency detection (via Depends-On field)
Context-aware revert decisions

Performance

Logical unit detection: <500ms (100 commits)
Dependency checking: <100ms (transitive depth 3)
No impact on normal git operations

Related Skills

track-management - Understand track/phase/task structure
workflow-patterns - Git commit conventions
git-expert - Advanced git operations
debugging - When revert is needed due to bugs

Memory Protocol (MANDATORY)

Before starting: Read .claude/context/memory/learnings.md

After completing:

New pattern discovered -> .claude/context/memory/learnings.md
Issue encountered -> .claude/context/memory/issues.md
Decision made -> .claude/context/memory/decisions.md

ASSUME INTERRUPTION: If it's not in memory, it didn't happen.