Imported from jimmypaolini/codebase (.agents/skills/restore-code/SKILL.md). Install upstream with npx skills add jimmypaolini/codebase --skill restore-code. Copyright stays with the author (MIT).

Restore Code From Backup

Recover code from backup artifacts with a preview-first workflow that minimizes additional loss.

When to Use This Skill

• After accidental destructive commands (reset --hard, clean, force-overwrite checkouts)
• After risky refactors or codemods introduced broad regressions
• After failed rebase or merge sequences where you need known-good state
• When files were deleted or overwritten and must be recovered quickly
• When a backup branch or stash exists and work must be restored safely

Keywords: restore code, recover backup, restore stash, recover branch snapshot, undo destructive change.

Recovery Sources Supported

• Backup branches (backup/*)
• Named stashes created for safety snapshots
• Specific commit snapshots (including backup commits)
• Selective file restore from any source reference

Prerequisites

• Run from repository root
• git is available
• Backup source exists or can be discovered
• Working tree state is inspectable

Decision Flow

1. If full workspace rollback is required, restore from backup branch.
2. If local uncommitted work must be rehydrated, restore from stash.
3. If only selected files are needed, perform selective file restore.
4. If the target state is uncertain, preview diffs first and restore incrementally.
5. If current work may still be needed, run backup-code before restoring.

Step-by-Step Workflow

1. Inspect Current And Recovery State

Run:

git status --short
git branch --show-current
git branch --list "backup/*"
git stash list --date=local

Record:

• Current branch
• Current uncommitted changes
• Available backup branches
• Candidate stash entry IDs

2. Choose Recovery Strategy

Strategy A: Restore Entire State From Backup Branch

Preview:

git diff --stat HEAD..backup/<source-branch>/<source-iso-timestamp>

Restore via reset to backup commit (destructive to current local state):

git reset --hard backup/<source-branch>/<source-iso-timestamp>

Alternative non-destructive approach:

git switch -c restore/<timestamp> backup/<source-branch>/<source-iso-timestamp>

Use this when broad rollback is needed.

Strategy B: Restore From Stash Snapshot

Preview stash contents:

git stash show --name-status "stash@{N}"
git stash show -p "stash@{N}" | head -n 120

Apply while keeping stash entry:

git stash apply "stash@{N}"

Apply and remove stash entry:

git stash pop "stash@{N}"

Use apply first when risk is unknown.

Strategy C: Restore Specific Files Only

From backup branch:

git restore --source backup/<source-branch>/<source-iso-timestamp> -- path/to/file.ts

From stash:

git restore --source "stash@{N}" -- path/to/file.ts

Use this when only partial recovery is needed.

3. Validate Recovery

Run:

git status --short
git diff --stat

Optional targeted checks:

pnpm exec nx affected --target=vitest --base=main

4. Finalize Recovery State

• Commit recovered changes if they are correct
• Keep source backup artifacts until recovery is confirmed
• Only delete backup branch/stash after verification

Completion Criteria

• Recovery source identified and validated
• Restore executed with expected scope (full or selective)
• Post-restore diff matches intended files and content
• Validation checks pass or known residual issues are documented

Troubleshooting

References

• Companion prevention workflow: backup-code
• Recovery history lookup: git reflog
• Safer partial restores: git restore --source <ref> -- <path>