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

Iron Laws

• NEVER force-push, hard reset, or discard staged changes without explicit user confirmation

• ALWAYS analyze impact (related commits, open files, uncommitted changes) before reverting

• NEVER revert a commit that affects more than the targeted scope — split the revert if needed

• ALWAYS verify the revert is successful with automated tests before marking complete

• NEVER skip the confirmation gate when reverting across multiple commits or phases

Anti-Patterns

Anti-Pattern Why It Fails Correct Approach

Reverting without impact analysis Unintended commits or files are also reverted Always analyze related commits, open files, and uncommitted changes first

Force-pushing after revert Destroys upstream history for other collaborators Use non-destructive revert commits instead of force-push

Skipping confirmation gate Accidental revert of critical work Always present a summary and require confirmation before executing

Reverting across multiple features Entangles unrelated changes in a single revert Split revert into targeted per-feature commits

Not running tests after revert Revert introduces new breakage Verify automated tests pass before marking revert complete

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.