Git phase restore

Git Phase Restore — Autonomous Development Phase Recovery

Leverage Git's full history to identify development phases and restore any project state automatically. No manual snapshots needed — Git already has everything.

---

Core Philosophy

Every Git repository already contains a complete record of every development phase. This skill teaches Claude to read that record intelligently and act on it:

• Commits with conventional messages → semantic phase boundaries
• Tags → explicit version milestones
• Branches → parallel development tracks
• Timestamps → temporal navigation
• Diffs → understanding what each phase changed

Instead of maintaining separate snapshot systems, this skill mines Git itself as the single source of truth.

---

When to Trigger

Always trigger this skill when the user wants to:

Intent	Example phrases
Restore a phase	"go back to when auth worked", "restore to v1.2", "undo last feature"
Explore history	"show project phases", "what was the state on March 1st", "git timeline"
Find a regression	"when did this bug appear", "find when X broke", "bisect this issue"
Compare phases	"diff between auth and current", "what changed since last week"
Inspect a past state	"show me the code before the refactor", "what did file X look like in phase Y"
Undo / rollback	"roll back", "undo", "revert", "go back" (in any Git project context)

---

Phase Detection Strategy

Development phases are identified by analyzing Git history through multiple lenses. Run scripts/detect_phases.sh in the project root to get a structured phase map, or follow the manual steps below.

1. Tag-Based Phases (highest confidence)

Tags are explicit developer-placed milestones. Always check these first.

# List all tags with dates and messages
git tag -l --sort=-creatordate --format='%(creatordate:short) %(refname:short) %(subject)'

2. Semantic Commit Phases (high confidence)

Parse conventional commit messages to detect phase boundaries. A new phase starts when:

• A feat: commit introduces a major new capability
• Multiple related commits cluster around a single feature/module
• A refactor: or chore: commit restructures the project
• A merge commit lands a feature branch

# Show commit history with type prefixes for phase detection
git log --oneline --decorate --all --date=short --format='%h %ad %s'

Group consecutive commits by their semantic prefix and the files they touch. A phase = a cluster of commits that share a purpose.

3. Branch-Based Phases

Each feature/bugfix branch represents a development phase.

# All branches (local + remote) with last commit date
git branch -a --sort=-committerdate --format='%(committerdate:short) %(refname:short)'

# Merged branches = completed phases
git branch --merged main

4. Time-Based Phases

When the user references a date or relative time period.

# Commits in a date range
git log --after="2025-01-01" --before="2025-02-01" --oneline

# Find the exact commit at a point in time
git rev-list -1 --before="2025-01-15" HEAD

5. File-Change-Based Phases

When the user references a specific feature or module, find phases by file paths.

# All commits that touched a specific path
git log --oneline -- src/auth/

# First and last commit touching a path = phase boundaries
git log --diff-filter=A --oneline -- src/auth/  # First appearance
git log -1 --oneline -- src/auth/                # Last change

---

Core Workflows

Workflow 1: List Project Phases

Trigger: "show phases", "project timeline", "what phases exist"

Steps:

1. Verify the project is a Git repository (git rev-parse --is-inside-work-tree)
2. Run phase detection across all lenses (tags → semantic → branches → time)
3. Present a structured timeline to the user:

PROJECT PHASE TIMELINE
━━━━━━━━━━━━━━━━━━━━━
Phase 1: Project Init          [abc1234] 2025-01-10
  └─ Initial scaffold, deps, config

Phase 2: Database Layer        [def5678] 2025-01-12 → [ghi9012] 2025-01-15
  └─ Room setup, DAOs, migrations (12 commits)

Phase 3: Auth System           [jkl3456] 2025-01-16 → [mno7890] 2025-01-22
  └─ JWT auth, login/register, token refresh (18 commits)
  └─ TAG: v0.1.0-alpha

Phase 4: Profile Feature       [pqr1234] 2025-01-23 → [stu5678] 2025-01-28
  └─ User profile CRUD, avatar upload (9 commits)

Phase 5: Current (HEAD)        [vwx9012] 2025-01-29 → now
  └─ Settings screen, bug fixes (6 commits)

4. Ask the user which phase they want to explore or restore.

---

Workflow 2: Restore to a Specific Phase

Trigger: "restore to phase X", "go back to [tag/commit/date/description]"

Steps:

1. Identify the target commit:

   • If tag: git rev-parse <tag>
   • If commit hash: use directly
   • If date: git rev-list -1 --before="<date>" HEAD
   • If description: search commit messages: git log --all --grep="<keyword>" --oneline
   • If phase name: use phase detection to find the boundary commit

2. Safety check — protect current work:

   # Check for uncommitted changes
   git status --porcelain
   
   # If dirty, auto-stash
   git stash push -m "auto-stash before phase restore $(date +%Y%m%d_%H%M%S)"
   

3. Choose restoration strategy (present options to user if ambiguous):

   Option A: Detached HEAD inspection (non-destructive, default for "show me")

   git checkout <target-commit>
   # User can look around, then return with:
   git checkout -
   

   Option B: New branch from phase (recommended for "restore and continue")

   git checkout -b restore/<phase-label> <target-commit>
   

   Option C: Hard reset (destructive — ONLY with explicit user confirmation)

   git reset --hard <target-commit>
   # Original HEAD saved in reflog for 90 days
   

   Option D: Revert range (safe undo of specific phases)

   git revert --no-commit <start-commit>..<end-commit>
   git commit -m "revert: undo phase [label] (commits <start>..<end>)"
   

4. Post-restore verification:

   # Confirm HEAD is where expected
   git log -1 --oneline
   
   # Show what's different from where we were
   git diff --stat <original-head> HEAD
   

5. Report to user:

   • Which commit was restored
   • Which strategy was used
   • How to get back (reflog, stash, branch name)
   • What files changed

---

Workflow 3: Find When Something Broke (Git Bisect)

Trigger: "when did X break", "find the regression", "bisect"

Steps:

1. Identify the "good" state (when it last worked) and "bad" state (current or reported)
2. Run automated bisect:

git bisect start
git bisect bad HEAD
git bisect good <known-good-commit>

# If there's a test command:
git bisect run <test-command>

# Otherwise, manual bisect — Claude checks each midpoint

3. Report the exact commit that introduced the issue
4. Offer to revert just that commit: git revert <bad-commit>

---

Workflow 4: Compare Phases

Trigger: "diff between phases", "what changed since X", "compare auth phase to current"

Steps:

# Stat summary between two phase boundary commits
git diff --stat <phase-start>..<phase-end>

# Detailed diff for specific files
git diff <commit-a> <commit-b> -- <path>

# Show which files were added/modified/deleted
git diff --name-status <commit-a> <commit-b>

Present as a structured summary:

• Files added / modified / deleted
• Lines added / removed per file
• Key changes in plain English

---

Workflow 5: Inspect a File at a Past Phase

Trigger: "show me file X at phase Y", "what did config look like before"

# Show file content at a specific commit
git show <commit>:<file-path>

# Compare a file between two commits
git diff <commit-a> <commit-b> -- <file-path>

---

Safety Rules

These are non-negotiable safeguards:

1. Never force-push to shared branches (main, master, develop) without explicit user confirmation
2. Always stash or commit uncommitted work before any checkout or reset
3. Prefer non-destructive operations — detached HEAD and new branches over hard resets
4. Always tell the user the reflog entry so they can recover: git reflog shows the safety net
5. Verify the repo is clean before any restoration — git status --porcelain must be empty or stashed
6. Log the restore action — if project-history or restore-points skills are active, update their logs too
7. Never rewrite history on branches that others may have pulled from

---

Automatic Phase Labeling

When commits follow conventional commit format (feat:, fix:, refactor:, etc.), Claude should auto-generate human-readable phase labels:

Commit pattern	Auto-label
feat: add user authentication	"Auth System"
feat: implement payment gateway	"Payment Integration"
refactor: extract service layer	"Service Layer Refactor"
chore: initial project setup	"Project Init"
Cluster of fix: commits	"Bug Fix Sprint"
Merge of feature/X branch	Phase named after branch

---

Integration with Other Skills

• git-workflow: This skill handles backward navigation; git-workflow handles forward progress. They complement each other.
• project-history: After a restore, update PROJECT_HISTORY.md's Active Context to reflect the restored state.
• project-restore-points: If the user also has filesystem snapshots, cross-reference them with Git phases for richer context.
• codebase-understanding: Before restoring, understand the current codebase structure so the restore doesn't break active work.

---

Quick Reference Commands

# Phase detection
git log --oneline --graph --decorate --all          # Visual history
git tag -l --sort=-creatordate                       # Tags = milestones
git branch -a --sort=-committerdate                  # Branches = phases

# Time travel
git checkout <commit>                                # Inspect (detached HEAD)
git checkout -b restore/<label> <commit>             # Restore as branch
git stash push -m "before restore"                   # Save current work

# Investigation
git bisect start && git bisect bad && git bisect good <commit>
git log --all --grep="<keyword>" --oneline           # Search commits
git log --after="<date>" --before="<date>" --oneline # Time range

# Recovery (always available)
git reflog                                           # Full undo history
git stash list                                       # Stashed work
git checkout -                                       # Go back to previous branch

---

Error Handling

Situation	Action
Not a git repo	Tell user, offer to git init + initial commit
Dirty working tree	Auto-stash with descriptive message
Commit not found	Broaden search: try --all, check reflog, search by message
Merge conflicts on revert	Show conflicts, help resolve, or abort and try different strategy
Detached HEAD confusion	Explain clearly, offer to create a branch or return
User wants to undo the restore	Use reflog: git reset --hard HEAD@{1} or pop stash