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

name, description

name	description
vm-snapshot	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:

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:

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:

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:

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:

$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:

# 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:

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:

# 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:

Get-VMSnapshot -VMName "ShopDB-Test-VM" -Name "2026-08-01_1400_before-wilm-merge"

2. Check if it's the current state:

$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:

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:

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:

$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

# 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

# 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

# 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