shopdb-flask/.claude/skills/vm-snapshot.md

---
name: vm-snapshot
description: Create, restore, list, and manage Hyper-V VM snapshots - 78 hrs/year time savings
---

# VM Snapshot Management

Comprehensive Hyper-V snapshot management for test VMs. Saves ~78 hrs/year by automating manual snapshot workflow.

## What This Skill Does

Complete snapshot lifecycle:
1. Create snapshot with descriptive name
2. List all snapshots with dates and descriptions
3. Restore to specific snapshot
4. Delete old snapshots (cleanup)
5. Verify VM state after restore
6. Automated pre/post-snapshot health checks

## Prerequisites

**Hyper-V permissions required:**
- Hyper-V Administrator group membership
- Or: Run PowerShell as Administrator

**VM details:**
- Name: ShopDB-Test-VM (or user-specified)
- Location: Hyper-V on local workstation
- Must be accessible via Get-VM cmdlet

## Workflow

### Common Operation: Create Snapshot

Most frequent use case - create snapshot before risky changes.

**Usage:** `/vm-snapshot create "description of what's about to change"`

**Steps:**

1. **Verify VM state:**
```powershell
Get-VM -Name "ShopDB-Test-VM" | Select-Object Name, State, Uptime
```

Expected: Running (preferred) or Stopped (acceptable)

2. **Generate snapshot name:**
```
Format: YYYY-MM-DD_HHmm_description
Example: 2026-09-11_1430_before-agent-deploy
```

Short descriptions preferred (< 50 chars).

3. **Create snapshot:**
```powershell
Checkpoint-VM -Name "ShopDB-Test-VM" -SnapshotName "2026-09-11_1430_before-agent-deploy"
```

**Monitor for:**
- Snapshot creation progress
- Disk space sufficient (snapshots can be large)
- No errors during checkpoint

4. **Verify snapshot created:**
```powershell
Get-VMSnapshot -VMName "ShopDB-Test-VM" -Name "2026-09-11_1430_before-agent-deploy"
```

Expected: Snapshot exists with correct name and timestamp.

5. **Report:**
```
Snapshot created successfully:
  Name: 2026-09-11_1430_before-agent-deploy
  VM: ShopDB-Test-VM
  Created: 2026-09-11 14:30:15
  Size: 2.3 GB
  Parent: 2026-09-10_0900_clean-state

You can now safely proceed with risky changes.
To restore: /vm-snapshot restore "2026-09-11_1430_before-agent-deploy"
```

### List All Snapshots

**Usage:** `/vm-snapshot list`

**Show snapshot tree:**
```powershell
Get-VMSnapshot -VMName "ShopDB-Test-VM" | 
  Select-Object Name, CreationTime, ParentSnapshotName, SizeMB |
  Sort-Object CreationTime -Descending
```

**Format output:**
```
Snapshots for ShopDB-Test-VM:

Recent (last 7 days):
  2026-09-11_1430_before-agent-deploy (2.3 GB) - 2 hours ago
  2026-09-10_0900_clean-state (1.8 GB) - 1 day ago
  2026-09-09_1600_test-endpoints (2.1 GB) - 2 days ago

Older (7-30 days):
  2026-09-01_1200_baseline (1.5 GB) - 10 days ago
  2026-08-28_0800_production-mirror (3.2 GB) - 14 days ago

Old (>30 days, consider cleanup):
  2026-08-15_1000_initial-setup (1.2 GB) - 27 days ago
  2026-08-01_1400_before-wilm-merge (2.8 GB) - 41 days ago [CLEANUP CANDIDATE]

Total snapshots: 7
Total disk space: 14.9 GB

Cleanup recommendations:
- Keep "baseline" and "production-mirror" (important)
- Remove "2026-08-01_1400_before-wilm-merge" (41 days old, > 30 day threshold)
```

### Restore to Snapshot

**Usage:** `/vm-snapshot restore "snapshot-name"`

**WARNING: WARNING: This will discard ALL changes since snapshot was created!**

**Steps:**

1. **Confirm restoration:**
Ask user to confirm:
```
WARNING:  RESTORE WARNING:

You are about to restore VM to snapshot:
  2026-09-10_0900_clean-state (created 1 day ago)

This will DISCARD all changes made since:
- Any agent deployments after Sept 10, 9:00 AM
- Any data added to ShopDB since Sept 10
- Any configuration changes on VM

Are you sure you want to proceed?
  Type 'yes' to restore, anything else to cancel:
```

2. **Check VM state:**
```powershell
$vm = Get-VM -Name "ShopDB-Test-VM"
if ($vm.State -eq "Running") {
    Write-Host "VM is running, will be stopped for restore"
}
```

3. **Perform restore:**
```powershell
# Stop VM if running
if ((Get-VM -Name "ShopDB-Test-VM").State -eq "Running") {
    Stop-VM -Name "ShopDB-Test-VM" -Force
}

# Restore snapshot
Restore-VMSnapshot -Name "2026-09-10_0900_clean-state" -VMName "ShopDB-Test-VM" -Confirm:$false

# Start VM
Start-VM -Name "ShopDB-Test-VM"
```

4. **Wait for VM to boot:**
```powershell
Write-Host "Waiting for VM to boot..."
Start-Sleep -Seconds 30

# Wait for network
while (-not (Test-Connection -ComputerName 192.168.100.10 -Count 1 -Quiet)) {
    Write-Host "Waiting for VM network..."
    Start-Sleep -Seconds 5
}
```

5. **Verify VM state:**
```bash
# SSH to VM
ssh -i ~/.ssh/vm_key SupportUser@192.168.100.10 "Get-Service ShopDBEndpointAgent"
```

Expected: Service exists (may be stopped, depends on snapshot state)

6. **Report:**
```
VM restored successfully:
  Snapshot: 2026-09-10_0900_clean-state
  VM State: Running
  Network: Accessible at 192.168.100.10
  SSH: Connected

Post-restore checklist:
  1. Verify agent service state
  2. Check endpoint reporting in ShopDB UI
  3. Test any workflows that depend on VM state

VM is ready for use.
```

### Delete Snapshot(s)

**Usage:** `/vm-snapshot delete "snapshot-name"`

or

**Usage:** `/vm-snapshot cleanup` (interactive cleanup of old snapshots)

**Single snapshot deletion:**

1. **Verify snapshot exists:**
```powershell
Get-VMSnapshot -VMName "ShopDB-Test-VM" -Name "2026-08-01_1400_before-wilm-merge"
```

2. **Check if it's the current state:**
```powershell
$current = (Get-VM -Name "ShopDB-Test-VM").ParentCheckpointId
$snapshot = (Get-VMSnapshot -VMName "ShopDB-Test-VM" -Name "2026-08-01_1400_before-wilm-merge").Id

if ($current -eq $snapshot) {
    Write-Error "Cannot delete snapshot: VM is currently at this state"
}
```

3. **Delete snapshot:**
```powershell
Remove-VMSnapshot -VMName "ShopDB-Test-VM" -Name "2026-08-01_1400_before-wilm-merge"
```

**Note:** Hyper-V will merge snapshot disk into parent (can take time for large snapshots)

4. **Monitor merge progress:**
```powershell
while ((Get-VMSnapshot -VMName "ShopDB-Test-VM" -Name "2026-08-01_1400_before-wilm-merge" -ErrorAction SilentlyContinue)) {
    Write-Host "Merging snapshot..."
    Start-Sleep -Seconds 5
}
```

5. **Report:**
```
Snapshot deleted:
  Name: 2026-08-01_1400_before-wilm-merge
  Disk space freed: ~2.8 GB
  Merge time: 45 seconds
```

**Automated cleanup:**

For `/vm-snapshot cleanup`:

1. List snapshots older than 30 days
2. Exclude important snapshots:
   - Contains "baseline" in name
   - Contains "production" in name
   - Marked as "Production" in description
3. Show cleanup candidates
4. Ask user to confirm each deletion
5. Delete confirmed snapshots
6. Report total space freed

### Export Snapshot (Advanced)

**Usage:** `/vm-snapshot export "snapshot-name" "C:\Exports\path"`

Exports snapshot to separate location for long-term archival:

```powershell
$snapshot = Get-VMSnapshot -VMName "ShopDB-Test-VM" -Name "2026-09-10_0900_clean-state"
Export-VMSnapshot -VMSnapshot $snapshot -Path "C:\Exports\ShopDB-Snapshots\"
```

**Use cases:**
- Archive known-good states
- Transfer snapshot to another machine
- Backup before major infrastructure changes

## Common Workflows

### Before Risky Change

```bash
# 1. Create snapshot
/vm-snapshot create "before-database-migration"

# 2. Make risky change
# ... deploy code, run migration, etc.

# 3. If failed, restore
/vm-snapshot restore "2026-09-11_1430_before-database-migration"

# 4. If succeeded, keep snapshot for a while
# (cleanup later with /vm-snapshot cleanup)
```

### Weekly Cleanup

```bash
# 1. List snapshots
/vm-snapshot list

# 2. Review old snapshots (> 30 days)
# 3. Run automated cleanup
/vm-snapshot cleanup

# 4. Verify important snapshots remain
/vm-snapshot list
```

### Baseline Management

```bash
# Create monthly baseline
/vm-snapshot create "baseline-$(date +%Y-%m)"

# Mark as important (manual: add "KEEP" to description)
# This prevents automated cleanup from removing it
```

## Troubleshooting

**"Insufficient disk space":**
- Check Hyper-V storage location free space
- Run `/vm-snapshot cleanup` to remove old snapshots
- Consider moving VM to larger disk

**"Access denied":**
- Run PowerShell as Administrator
- Verify Hyper-V Administrator group membership
- Check Hyper-V service is running

**"VM is in wrong state":**
- Some operations require VM stopped
- Stop VM: `Stop-VM -Name "ShopDB-Test-VM" -Force`
- Retry operation

**Snapshot merge takes too long:**
- Normal for large snapshots (can take 10+ minutes)
- Do not interrupt merge process
- Avoid creating too many snapshots (disk I/O intensive)

**Restored VM not accessible:**
- Wait 60+ seconds for VM to fully boot
- Check VM console in Hyper-V Manager
- Verify network adapter enabled in VM settings

## Best Practices

**Naming convention:**
- Use `YYYY-MM-DD_HHmm_description` format
- Keep description concise (< 50 chars)
- Include "before-" prefix for pre-change snapshots

**Snapshot frequency:**
- Before risky changes: Always
- Daily development: Optional (creates disk bloat)
- Weekly baseline: Recommended

**Cleanup schedule:**
- Review snapshots weekly
- Remove snapshots > 30 days (unless important)
- Keep at least one "baseline" snapshot per month

**Important snapshots:**
- Tag with "KEEP", "baseline", or "production"
- Document purpose in description
- Export to separate location for long-term storage

## Time Savings

**Manual snapshot workflow:** ~15 minutes
- Open Hyper-V Manager
- Navigate to VM
- Create checkpoint
- Name snapshot
- Wait for confirmation
- Verify in list

**With this skill:** ~30 seconds
- Type `/vm-snapshot create "description"`
- Skill handles rest automatically

**Annual savings:** 78 hours (based on 312 snapshots/year)

## Related

- [[vm-ssh-access]] - SSH access to VM
- [[agent-deployment]] - Agent deployment workflow
- `.claude/setup/VM-SNAPSHOT-GUIDE.md` - Detailed Hyper-V snapshot guide
- `.claude/setup/VM-USERS.md` - VM user accounts