Git-aware smart revert for tracks, phases, and tasks. Handles rewritten history, finds related commits, and provides safe rollback with multiple confirmation gates.
Git-aware smart revert for tracks, phases, and tasks. Handles rewritten history, finds related commits, and provides safe rollback with multiple confirmation gates.
model
sonnet
invoked_by
both
user_invocable
true
tools
["Read","Bash","Glob","Grep","Write","Edit"]
best_practices
["Always require user confirmation before any destructive action","Handle ghost commits (rewritten history) gracefully","Find ALL related commits (implementation + plan updates)","Present clear execution plan before reverting","Verify plan state after revert completes"]
error_handling
strict
streaming
supported
source
builtin
trust_score
100
provenance_sha
665f8d72f1662bda
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
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:
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 notesconst groups = await logicalUnitTracker.groupByTask(repoPath, 'HEAD~10..HEAD');
// Returns: { "6": [{hash, message, note}], "7": [{...}] }// Find dependenciesconst deps = await logicalUnitTracker.findDependencies(repoPath, '7', { transitive: true });
// Returns: ["6"] if Task #7 depends on Task #6// Check safety before revertingconst safety = await logicalUnitTracker.checkRevertSafety(repoPath, '6');
// Returns: { safe: boolean, blockers: [], warning: string }// Execute revert for entire taskconst result = await logicalUnitTracker.revertTask(repoPath, '6');
// Returns: { success: boolean, conflicts: boolean, message: string }// Find task by nameconst 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:
