Safe git revert command (/gsd-undo)

[davesienkowski]

Pre-submission checklist

• I have searched existing issues and discussions -- this has not been proposed and declined before
• I have read CONTRIBUTING.md and understand that I must wait for approved-feature before writing any code
• I have read the existing GSD commands and workflows and confirmed this feature does not duplicate existing behavior
• This feature solves a problem for solo developers using AI coding tools, not a personal preference or workflow I happen to like

Feature name

Safe git revert command (/gsd-undo)

Type of addition

New command (slash command or CLI flag)

The solo developer problem

When a GSD phase or plan produces bad output -- broken code, wrong approach, or corrupted state -- there is no GSD-native way to safely roll back the git commits made during that phase. The developer must manually identify which commits belong to the phase, figure out dependency ordering, and run git revert commands. This is error-prone, especially when a phase touched many files across multiple commits. A solo developer without a reviewer is likely to miss commits or revert in the wrong order.

What this feature adds

A new /gsd-undo command that safely reverts GSD phase or plan commits using git revert --no-commit (never git reset -- history is always preserved).

Three modes:

• --last N: Show the last N GSD commits (filtered by conventional commit pattern) for interactive selection. The developer picks which commits to revert.
• --phase NN: Revert all commits for a specific phase. Reads the phase manifest (.planning/.phase-manifest.json) first; falls back to git log filtering by phase number in commit scope.
• --plan NN-MM: Revert all commits for a specific plan within a phase.

Safety features:

• Dependency check: Before reverting, checks if later phases depend on the target phase's output. If so, warns the developer and requires confirmation.
• Confirmation gate: Displays the exact commits that will be reverted and asks for confirmation before executing.
• Atomic revert: All reverts are staged together in a single commit, not applied one at a time.

Example usage:

/gsd-undo --phase 03
> Found 4 commits for Phase 03 via phase manifest.
> WARNING: Phase 04 depends on Phase 03 output. Reverting may break Phase 04.
> Commits to revert:
>   abc1234 feat(03-01): implement auth endpoint
>   def5678 feat(03-02): add auth middleware
>   ghi9012 test(03): add auth tests
>   jkl3456 docs(03): complete phase summary
> Proceed? [y/N]

Full scope of changes

Files created:

• commands/gsd/undo.md -- slash command definition with --last/--phase/--plan flags
• get-shit-done/workflows/undo.md -- revert workflow with manifest lookup, dependency check, confirmation gate

Files modified:

• None required. The command and workflow are self-contained.

User stories

1. As a solo developer who just completed a phase that produced broken code, I want to run /gsd-undo --phase 03 to safely revert all commits from that phase, so I can re-plan and re-execute without manually identifying and reverting individual commits.
2. As a solo developer who made a mistake in one specific plan, I want to run /gsd-undo --plan 03-02 to revert only that plan's commits while keeping the rest of the phase intact.

Acceptance criteria

• /gsd-undo --last 5 shows the last 5 GSD conventional commits and allows interactive selection
• /gsd-undo --phase NN reads phase manifest first, falls back to git log filtering
• /gsd-undo --plan NN-MM reverts only commits matching the specific plan
• All reverts use git revert --no-commit (never git reset)
• Dependency check warns when later phases depend on the target phase
• Confirmation gate displays exact commits before executing
• Reverts are committed as a single atomic revert commit
• The command is discoverable via /gsd-help
• Running with no arguments displays usage help

Which area does this primarily affect?

Core workflow (init, plan, build, verify)

Applicable runtimes

• Claude Code
• All runtimes (runtime-agnostic)

Breaking changes assessment

None. This is an entirely new command. No existing behavior is modified.

Maintenance burden

Low-medium. The phase manifest dependency (.planning/.phase-manifest.json) means the command works best when the manifest is maintained. The git log fallback ensures it works even without a manifest but with lower accuracy. The dependency check logic needs to stay in sync with how phases express dependencies in ROADMAP.md.

Alternatives considered

1. Manual git revert -- Error-prone for multi-commit phases. The developer must identify which commits belong to which phase.
2. Planning state rollback only (no git revert) -- Does not address the actual code changes. Rolling back .planning/ state without reverting the code leaves the project in an inconsistent state.
3. git reset --hard -- Destructive and loses history. GSD must preserve history for auditability.

Prior art and references

Replaces #1719 (which incorrectly described this as a planning state rollback). Split from #1686 per maintainer feedback. Uses git revert --no-commit pattern from Git documentation.

[trek-e]

✅ Approved as feature.

Strong safety-first design. git revert --no-commit only, confirmation gate, dependency check — this is exactly how an undo command should work. Self-contained scope with no modifications to existing files.

Implementation notes:

• The phase manifest lookup → git log fallback is the right priority order
• The atomic single-commit revert is important — don't let partial reverts leave the repo in a broken state
• Dependency check should be conservative: warn and require confirmation, never silently skip
• Consider including the revert commit message format in the spec (e.g., revert(03): undo phase 03 — <reason>)

@davesienkowski — labeled approved-feature. You're clear to implement.