git-revert-safety

name	git-revert-safety
description	Apply when reverting commits, undoing merges, or recovering from branch contamination. Covers collateral damage verification (manifest, package.json, CHANGELOG, lockfiles), cherry-pick vs revert decision matrix, partial-revert detection, merge-parent handling, and post-revert CI verification. Prevents the most common revert failure mode: version metadata regression from git reverse-apply.
effort	small
triggers	["git revert","revert commit","revert merge","undo merge","reverse-apply","branch contamination","cherry-pick recovery","release-please duplicate tag"]
generated_from_knowledge	[]
source_knowledge_ids	["f07c1f4d-9bb0-4219-9804-26aa8efe8146"]
generated_at	2026-06-14T16:50:00.000Z
confidence	0.8
status	active
version	4
skill_origin	generated
provenance_note	Re-linked to current knowledge entries (version 4). The original source ID 11f0e8cb... is no longer present in the active knowledge store. The skill body and behavior are unchanged; only source_knowledge_ids metadata was updated to point to the current lesson about verifying pre-existing state on parent commit, which is directly relevant to post-revert CI verification.

Git Revert Safety Protocol

Two internal workflows: Safe Git Revert (Steps 1-4) and Branch Contamination Recovery (Steps 5-6). Use the first when reverting known commits. Use the second when the wrong code was merged and you need a clean slate.

---

Workflow A — Safe Git Revert

Step 1 — Collateral Damage Assessment

Before reverting, list ALL files touched by each commit being reverted. Use the correct command for the situation:

Single commit:

git show --name-only --format= <sha>

Multiple commits (contiguous range):

git diff --name-only <commit-before-first>..<last-commit-sha>

Merge commit — inspect all parents (handles octopus merges with 3+ parents):

git show --format="%H %P" <merge-sha>   # Shows ALL parent SHAs
git log --oneline <merge-sha>^1         # First parent (usually main)
git log --oneline <merge-sha>^2         # Second parent (feature branch)
# For octopus merges: also inspect ^3, ^4, etc.

Identify which files in the diff are NOT part of the feature being reverted:

• .release-please-manifest.json — version state
• package.json — version field + dependency additions/removals
• CHANGELOG.md — release history
• Lockfiles (bun.lock, package-lock.json) — dependency graph
• Any config files modified by release PRs between the feature and now

dist/ is generated and NOT committed, so it never appears in a revert diff and needs no rebuild+commit as part of a revert — reverting the source is enough.

Gate: If ANY version metadata or dependency file appears in the diff, you MUST verify post-revert state (Step 3).

Step 2 — Choose Recovery Strategy

Scenario	Strategy	Caveat
Single commit that does NOT touch release/build artifacts	git revert <sha>