Back to Details

smart-revert

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Smart Revert

智能撤销

Git-aware intelligent revert system for reverting logical work units (tracks, phases, tasks) while handling complex Git histories.
一款感知Git的智能撤销系统，可针对逻辑工作单元（工作流、阶段、任务）执行撤销操作，同时能处理复杂的Git提交历史。

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
  • 撤销需要重做的已完成任务
  • 回滚未达要求的整个阶段
  • 在审核不通过后撤销工作流（track）变更
  • 从实现错误中恢复
  • 清理中断的工作内容

Core Concepts

核心概念

Logical vs Physical Revert

逻辑撤销 vs 物理撤销

TypeDescriptionExample
LogicalRevert a track/phase/task as defined in plan.md"Revert Task 2.1"
PhysicalRevert specific Git commits"Revert commit abc1234"
This skill bridges the gap: given a logical target, it finds all physical commits.
类型描述示例
逻辑撤销按照plan.md中的定义撤销工作流/阶段/任务"撤销任务2.1"
物理撤销撤销特定的Git提交"撤销提交abc1234"
本工具填补了两者之间的空白：给定一个逻辑目标，它会自动查找所有相关的物理提交。

4-Phase Protocol

四阶段流程

Phase 1: Interactive Target Selection

阶段1：交互式目标选择

  1. Check for explicit target: Did user specify what to revert?
  2. If no target: Present guided menu of candidates:
    • First: In-progress items (
      [~]
      )
    • Fallback: Recently completed items (
      [x]
      )
  3. 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?
  1. 检查明确目标：用户是否指定了要撤销的内容？
  2. 若无目标：提供候选内容的引导菜单：
    • 优先：进行中的项目（
      [~]
      ）
    • 备选：最近完成的项目（
      [x]
      ）
  3. 确认意图：在执行前验证理解是否正确
菜单格式：
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

阶段2：Git协调

Goal: Find ALL commits related to the logical unit.
  1. Find implementation commits:
    • Extract SHAs from plan.md (
      [x] Task: Description \
      abc1234``)
    • Handle "ghost commits" (rebased/squashed)
  2. Find plan-update commits:
    • For each implementation SHA, find the following plan.md update
  3. 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)
目标：找到与逻辑单元相关的所有提交。
  1. 查找实现提交：
    • 从plan.md中提取SHA值（格式：
      [x] Task: Description \\
      abc1234\``）
    • 处理“幽灵提交”（已变基/合并压缩的提交）
  2. 查找计划更新提交：
    • 针对每个实现提交的SHA，查找对应的plan.md更新提交
  3. 查找工作流创建提交（若撤销整个工作流）：
    • 在Git日志中搜索track条目被添加到tracks.md的时间点
处理幽灵提交：
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

阶段3：执行计划确认

Present clear summary before any action:
undefined
在执行任何操作前，展示清晰的摘要：
undefined

Revert Execution Plan

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
undefined
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
undefined

Phase 4: Execution & Verification

阶段4：执行与验证

  1. Execute reverts (newest to oldest):
    bash
    git revert --no-edit <sha>
  2. 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
  3. Verify plan state: Re-read plan.md to confirm status reset
  4. Announce completion: Confirm revert succeeded
  1. 执行撤销操作（从最新提交到最早提交）：
    bash
    git revert --no-edit <sha>
  2. 处理冲突：若发生冲突，提供指导：
    Merge conflict detected. Please resolve manually:
1. Edit conflicted files
2. Run: git add .
3. Run: git revert --continue
  3. 验证计划状态：重新读取plan.md以确认状态已重置
  4. 完成通知：确认撤销操作成功

Commit Identification Strategies

提交识别策略

Finding Implementation Commits

查找实现提交

bash
undefined
bash
undefined

Extract SHA from plan.md

Extract SHA from plan.md

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

Verify SHA exists

Verify SHA exists

git cat-file -t <sha>
undefined
git cat-file -t <sha>
undefined

Finding Plan Update Commits

查找计划更新提交

bash
undefined
bash
undefined

Find commits that modified plan.md after implementation

Find commits that modified plan.md after implementation

git log --oneline -- path/to/plan.md | head -5
undefined
git log --oneline -- path/to/plan.md | head -5
undefined

Handling Rebased History

处理变基后的历史

bash
undefined
bash
undefined

Search by commit message similarity

Search by commit message similarity

git log --oneline --all | grep -i "implement validation"
git log --oneline --all | grep -i "implement validation"

Search by file changes

Search by file changes

git log --oneline --all -- src/models/user.py
undefined
git log --oneline --all -- src/models/user.py
undefined

Finding Track Creation

查找工作流创建记录

bash
undefined
bash
undefined

Find when track was added to registry

Find when track was added to registry

git log -p -- conductor/tracks.md | grep -B5 "Track: user-auth"
undefined
git log -p -- conductor/tracks.md | grep -B5 "Track: user-auth"
undefined

Safety Features

安全特性

Multiple Confirmation Gates

多重确认机制

GatePurposeWhen
Target confirmationVerify correct item selectedAfter selection
Execution plan reviewShow exactly what will happenBefore any git operation
Final go/no-goLast chance to cancelImmediately before revert
确认环节目的触发时机
目标确认验证选择的项目是否正确选择目标后
执行计划审核明确展示即将执行的操作任何Git操作执行前
最终确认最后一次取消机会即将执行撤销操作前

Conflict Handling

冲突处理

If 
git revert
fails:
  1. Do NOT force or continue automatically
  2. Explain what happened
  3. Provide manual resolution steps
  4. Offer to help after user resolves
若
git revert
执行失败：
  1. 请勿强制继续或自动执行
  2. 解释发生的问题
  3. 提供手动解决步骤
  4. 主动协助用户解决后的后续操作

Post-Revert Verification

撤销后验证

Always verify the plan file reflects the revert:
markdown
Before: [x] Task 2.1: Implement validation `abc1234`
After: [ ] Task 2.1: Implement validation
If plan state is inconsistent, offer to fix it.
始终验证计划文件是否反映了撤销结果：
markdown
Before: [x] Task 2.1: Implement validation `abc1234`
After: [ ] Task 2.1: Implement validation
若计划状态不一致，主动提出修复。

Example Scenarios

示例场景

Scenario 1: Revert Single Task

场景1：撤销单个任务

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
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

场景2：撤销整个阶段

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
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

场景3：处理幽灵提交

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]
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

与track-management集成

Read plan.md and tracks.md to understand work structure.
读取plan.md和tracks.md以理解工作结构。

With workflow-patterns

与workflow-patterns集成

Follow established commit conventions when creating revert commits.
在创建撤销提交时遵循既定的提交规范。

With context-driven-development

与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
  • 未经确认直接执行撤销
  • 忽略幽灵提交（静默失败）
  • 让plan.md处于不一致状态
  • 撤销后强制推送
  • 不做特殊处理就撤销合并提交

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)

与Git Notes集成（增强版 - 阶段1.5）

Logical Unit Identification

逻辑单元识别

Instead of asking "Which commits?", ask "Which feature/bug?"
Old Workflow:
  1. User: "Revert commit abc123"
  2. Agent: Runs 
    git revert abc123
New Workflow (Git Notes-Based):
  1. User: "Revert the dark mode feature"
  2. 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
不再询问“哪些提交？”，而是询问“哪个功能/BUG？”
旧工作流：
  1. 用户：“撤销提交abc123”
  2. 工具：执行
    git revert abc123
新工作流（基于Git Notes）：
  1. 用户：“撤销深色模式功能”
  2. 工具：
    • 在Git Notes中搜索“深色模式”或功能ID
    • 通过
      logical-unit-tracker.cjs
      查找所有相关提交
    • 展示：“是否撤销这些提交？[A, B, C]”
    • 用户：“是”
    • 执行：
      git revert -n C B A
      （逆序）
    • 结果：功能被干净地撤销

How It Works

工作原理

  1. Find Unit: Invoke 
    logical-unit-tracker.cjs
    to group commits by task
  2. Show Options: List tasks with commit count
    • Task #6: Dark Mode (2 commits)
    • Task #7: Button Refactor (3 commits)
  3. Confirm: User selects task to revert
  4. Check Dependencies: Warn if other tasks depend on this
  5. Execute: Revert all commits for task (reverse order)
  6. Verify: Show revert result and update git notes
  1. 查找单元：调用
    logical-unit-tracker.cjs
    按任务分组提交
  2. 展示选项：列出带提交数量的任务
    • 任务#6：深色模式（2个提交）
    • 任务#7：按钮重构（3个提交）
  3. 确认：用户选择要撤销的任务
  4. 检查依赖：若其他任务依赖当前任务，发出警告
  5. 执行：逆序撤销任务的所有提交
  6. 验证：展示撤销结果并更新Git Notes

Logical Unit Tracker API

逻辑单元追踪器API

javascript
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
javascript
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
按功能名称撤销：
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."
按任务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
依赖警告：
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
对用户：
  • 基于功能的撤销（而非提交级）
  • 无需记住提交哈希
  • 自动按正确顺序（逆时间序）执行
  • 依赖检查可防止破坏其他功能
安全性：
  • Git Notes为每个提交提供上下文
  • 逆序执行可减少冲突
  • 执行前验证
  • Git Notes中保留审计轨迹
自动化：
  • 与git-notes-audit钩子集成（自动创建笔记）
  • 与现有conductor工作流兼容
  • 无需手动维护笔记

Integration with git-notes-audit Hook

与git-notes-audit钩子集成

The 
git-notes-audit.cjs
hook automatically creates git notes for every commit:
json
{
  "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
git-notes-audit.cjs
钩子会自动为每个提交创建Git Notes：
json
{
  "taskId": "6",
  "timestamp": "2026-01-29T10:30:00Z",
  "author": "user@example.com",

  "metadata": {
    "phase": "implementation",
    "track": "user-auth_20250115"
  }
}
这实现了：
  • 自动任务分组（无需手动维护笔记）
  • 依赖检测（通过Depends-On字段）
  • 上下文感知的撤销决策

Performance

性能

  • Logical unit detection: <500ms (100 commits)
  • Dependency checking: <100ms (transitive depth 3)
  • No impact on normal git operations
  • 逻辑单元检测：<500ms（100个提交）
  • 依赖检查：<100ms（传递深度3）
  • 不影响正常Git操作

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
  • track-management
    - 理解工作流/阶段/任务结构
  • workflow-patterns
    - Git提交规范
  • git-expert
    - 高级Git操作
  • debugging
    - 当因BUG需要撤销时

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.
开始前： 读取
.claude/context/memory/learnings.md
完成后：
  • 发现新模式 -> 写入
    .claude/context/memory/learnings.md
  • 遇到问题 -> 写入
    .claude/context/memory/issues.md
  • 做出决策 -> 写入
    .claude/context/memory/decisions.md
假设会被中断：若未记录在记忆中，则视为未发生。",