startup-it-troubleshooting — Claude Code skill: IT fixes without

---
name: startup-it-troubleshooting
description: Practical IT troubleshooting playbooks for small teams without dedicated IT staff.
license: MIT
metadata:
  author: devops-skills
  version: "2.0"
---

# Startup IT Troubleshooting

Runbooks for startups and small teams where engineers double as the IT department.

## When to Use

You are the "accidental IT person." Nobody has IT in their title, but laptops freeze, Wi-Fi drops during investor demos, someone gets locked out of Google Workspace at midnight, and a new hire starts Monday with zero accounts. This skill gives you copy-paste commands to handle it all.

**Priority triage:** (1) Company-wide outages, (2) Executive/customer-facing blockers, (3) Team-wide degradations, (4) Individual workstation issues. Always ask: "How many people are affected?" and "Is revenue impacted?"

---

## SSO / Identity Lockouts

### Google Workspace via GAM

```bash
bash <(curl -s -S -L https://gam-shortn.appspot.com/gam-install)  # install GAM
gam oauth create                                                     # authorize

gam update user [email protected] password "TempPass123!" changepassword on  # reset password
gam update user [email protected] suspended off       # unsuspend locked-out user
gam user [email protected] signout                    # force sign-out all sessions
gam user [email protected] update backupcodes         # new MFA backup codes
gam user [email protected] turnoff2sv                 # disable 2SV (re-enable within 24h)
```

### Okta API

```bash
OKTA="company.okta.com"; T="your-api-token"; UID="00u1abcdef"
curl -X POST -H "Authorization: SSWS $T" "https://$OKTA/api/v1/users/$UID/lifecycle/unlock"
curl -X POST -H "Authorization: SSWS $T" "https://$OKTA/api/v1/users/$UID/lifecycle/reset_password?sendEmail=true"
curl -X POST -H "Authorization: SSWS $T" "https://$OKTA/api/v1/users/$UID/lifecycle/reset_factors"
curl -X DELETE -H "Authorization: SSWS $T" "https://$OKTA/api/v1/users/$UID/sessions"
```

**MFA recovery flow:** Verify identity via video call, generate backup codes or reset factors, have user re-enroll immediately, confirm old device is deregistered, log the incident.

---

## Network Troubleshooting

### Wi-Fi Debugging

```bash
# macOS
/System/Library/PrivateFrameworks/Apple80211.framework/Versions/Current/Resources/airport -I
networksetup -setairportpower en0 off && sleep 2 && networksetup -setairportpower en0 on
sudo dscacheutil -flushcache && sudo killall -HUP mDNSResponder

# Linux
nmcli device wifi list && nmcli connection show --active
nmcli device disconnect wlan0 && nmcli device connect wlan0
sudo systemd-resolve --flush-caches
```

```powershell
netsh wlan show interfaces
netsh wlan disconnect; netsh wlan connect name="OfficeWiFi"
ipconfig /flushdns
netsh winsock reset  # full stack reset, reboot after
```

### DNS Issues

```bash
nslookup company.com 8.8.8.8            # test against known-good DNS
dig @1.1.1.1 company.com                # Linux/macOS detail
sudo networksetup -setdnsservers Wi-Fi 8.8.8.8 8.8.4.4  # macOS temp override
```

```powershell
$a = Get-NetAdapter | Where-Object {$_.Status -eq "Up"}
Set-DnsClientServerAddress -InterfaceIndex $a.ifIndex -ServerAddresses ("8.8.8.8","8.8.4.4")
```

### VPN Not Connecting

```bash
nc -zv vpn.company.com 443                         # test port reachability
sudo wg show                                        # WireGuard status
sudo wg-quick down wg0 && sudo wg-quick up wg0     # restart WireGuard
tailscale status && sudo tailscale up --reset       # Tailscale re-auth
```

### Slow Internet

```bash
speedtest-cli --simple        # bandwidth test (pip install speedtest-cli)
ping -c 50 8.8.8.8            # packet loss check
networkQuality -s              # macOS 12+ bufferbloat test
```

---

## Laptop Performance

### Disk Space

```bash
df -h                                    # volume overview
du -sh ~/* | sort -rh | head -15         # biggest dirs in home
docker system df                         # Docker disk usage (common culprit)
docker system prune -a --volumes         # reclaim Docker space
brew cleanup --prune=all                 # macOS Homebrew cleanup
```

```powershell
Get-PSDrive -PSProvider FileSystem | Select Name,@{N='Free(GB)';E={[math]::Round($_.Free/1GB,2)}}
Get-ChildItem C:\ -Recurse -File -EA SilentlyContinue | Sort Length -Desc | Select -First 15 FullName,@{N='MB';E={[math]::Round($_.Length/1MB,2)}}
```

### Memory Pressure and Runaway Processes

```bash
# macOS
memory_pressure
top -o rsize -l 1 -n 10 -stats pid,command,rsize
pkill -f "Google Chrome Helper"

# Linux
free -h && ps aux --sort=-%mem | head -11
sudo dmesg | grep -i "oom\|out of memory"
```

```powershell
Get-Process | Sort WorkingSet64 -Desc | Select -First 10 Name,@{N='MB';E={[math]::Round($_.WorkingSet64/1MB,2)}}
Stop-Process -Name "Teams" -Force
```

### Battery Health

```bash
system_profiler SPPowerDataType | grep -E "Cycle Count|Condition"  # macOS
upower -i /org/freedesktop/UPower/devices/battery_BAT0             # Linux
```

```powershell
powercfg /batteryreport /output "$env:USERPROFILE\Desktop\battery.html"
```

---

## macOS Administration

```bash
profiles status -type enrollment          # MDM enrollment check
sudo systemsetup -setremotelogin on       # enable SSH for remote admin

# Homebrew fleet setup — standard Brewfile
cat > Brewfile <<'EOF'
brew "git"; brew "node"; brew "[email protected]"; brew "awscli"; brew "jq"; brew "gh"
cask "google-chrome"; cask "slack"; cask "1password"; cask "visual-studio-code"; cask "docker"; cask "zoom"
EOF
brew bundle install --file=Brewfile
brew bundle dump --file=~/Brewfile --force  # export current setup

# FileVault
sudo fdesetup status && sudo fdesetup enable  # store recovery key in 1Password

# Updates
softwareupdate -l && sudo softwareupdate -ia --restart
```

---

## Windows Administration

```powershell
gpresult /r; gpupdate /force             # check and refresh Group Policy

# Windows Update
Install-Module PSWindowsUpdate -Force -Scope CurrentUser
Install-WindowsUpdate -AcceptAll -AutoReboot
# If stuck: reset update components
Stop-Service wuauserv,cryptSvc,bits,msiserver -Force
Remove-Item "C:\Windows\SoftwareDistribution" -Recurse -Force
Start-Service wuauserv,cryptSvc,bits,msiserver

# BitLocker
manage-bde -status C:
Enable-BitLocker -MountPoint "C:" -EncryptionMethod XtsAes256 -UsedSpaceOnly -TpmProtector

# Remote Desktop
Set-ItemProperty -Path 'HKLM:\System\CurrentControlSet\Control\Terminal Server' -Name "fDenyTSConnections" -Value 0
Enable-NetFirewallRule -DisplayGroup "Remote Desktop"
```

---

## Linux Desktop

```bash
# Ubuntu — fix broken packages
sudo apt --fix-broken install && sudo dpkg --configure -a && sudo apt update && sudo apt upgrade -y

# Fedora — fix broken packages
sudo dnf check && sudo dnf distro-sync && sudo dnf update -y

# Service failures
systemctl --failed
journalctl -p err -b

# Drivers
sudo ubuntu-drivers autoinstall                    # Ubuntu proprietary drivers
lspci | grep -i vga && sudo lshw -C display        # GPU info
sudo dmesg | grep -i firmware                       # missing firmware

# Display issues
xrandr --auto                                       # reset to auto-detect
xrandr --output HDMI-1 --mode 1920x1080 --rate 60  # force resolution
echo $XDG_SESSION_TYPE                              # Wayland vs X11 check
```

---

## Email / Calendar Issues

### Google Workspace

```bash
gam user [email protected] show forwarding    # check rogue forwarding rules
gam user [email protected] delete forwarding  # remove forwarding
gam user [email protected] show delegates     # check email delegation
gam user [email protected] show filters       # check mail filters
```

### Microsoft 365

```powershell
Install-Module ExchangeOnlineManagement -Force -Scope CurrentUser
Connect-ExchangeOnline -UserPrincipalName [email protected]
Get-MessageTrace -SenderAddress [email protected] -StartDate (Get-Date).AddDays(-7) -EndDate (Get-Date)
Get-MailboxStatistics -Identity [email protected] | Select DisplayName,TotalItemSize
```

### Email Deliverability

```bash
dig TXT company.com | grep "v=spf1"             # SPF
dig TXT google._domainkey.company.com            # DKIM
dig TXT _dmarc.company.com                       # DMARC
```

---

## Onboarding Checklist

```bash
# 1. Google Workspace account
gam create user [email protected] firstname "Jane" lastname "Smith" \
  password "Welcome2Company!" changepassword on org "/Engineering"
gam update group [email protected] add member [email protected]

# 2. 1Password
op user provision --email [email protected] --name "Jane Smith"

# 3. Slack
curl -X POST "https://slack.com/api/admin.users.invite" \
  -H "Authorization: Bearer xoxp-your-admin-token" \
  -d "[email protected]&channel_ids=C01GENERAL,C02ENGINEERING&team_id=T01YOURTEAM"

# 4. GitHub
gh api orgs/your-company/invitations -f email="[email protected]" -f role="direct_member"
gh api orgs/your-company/teams/engineering/memberships/newhire-username -f role="member" -X PUT

# 5. VPN / Tailscale
tailscale up --authkey tskey-auth-abc123
```

### First-Day Setup Script (macOS)

Give new hires this script. It installs Homebrew, your standard tools from a hosted Brewfile, configures Git, authenticates GitHub CLI, clones core repos, and enables FileVault.

```bash
#!/bin/bash
set -e
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
curl -sL https://internal.company.com/setup/Brewfile -o /tmp/Brewfile && brew bundle install --file=/tmp/Brewfile
read -p "Full name: " N; read -p "Email: " E
git config --global user.name "$N" && git config --global user.email "$E" && git config --global pull.rebase true
gh auth login && mkdir -p ~/src && cd ~/src && gh repo clone your-company/main-app
sudo fdesetup enable
```

## Offboarding Checklist

Run these **immediately** when someone departs. Speed matters for security.

```bash
gam update user [email protected] suspended on             # 1. block all access
gam user [email protected] signout                         # 2. kill sessions
gam user [email protected] transfer drive [email protected]  # 3. transfer Drive
gam user [email protected] add delegate [email protected]    # 4. delegate email 30d
curl -X POST "https://slack.com/api/admin.users.remove" \
  -H "Authorization: Bearer xoxp-your-admin-token" \
  -d "user_id=U01DEPARTED&team_id=T01YOURTEAM"               # 5. remove Slack
gh api orgs/your-company/members/departed-username -X DELETE   # 6. remove GitHub
op user suspend [email protected]                           # 7. revoke 1Password
aws iam delete-login-profile --user-name departed              # 8. revoke AWS console
aws iam list-access-keys --user-name departed                  #    then delete each key
echo "$(date -u +%Y-%m-%dT%H:%M:%SZ) Offboarded [email protected]" >> ~/offboarding-log.txt
```

---

## Video Conferencing

```bash
# macOS
lsof | grep "AppleCamera\|VDC"          # check what owns the camera
pkill -f zoom.us && open -a zoom.us      # restart Zoom
tccutil reset Camera                     # reset camera permissions

# Linux
pactl list short sources                 # list mics
pactl set-source-mute @DEFAULT_SOURCE@ 0 # unmute mic
```

```powershell
Get-CimInstance Win32_SoundDevice | Select Name, Status
```

**Quick fixes:** No audio = check OS mute + correct device. No video = close other conferencing apps. Echo = use headphones. Choppy = need 3+ Mbps upload.

---

## Printer / Peripheral Issues

```bash
# macOS
lpstat -p -d && cancel -a                                    # list printers, clear queue
sudo launchctl stop org.cups.cupsd && sudo launchctl start org.cups.cupsd
system_profiler SPUSBDataType            # USB devices

# Linux
sudo systemctl restart cups              # restart print system
lsusb && dmesg | tail -20               # USB diagnostics
```

```powershell
Restart-Service Spooler -Force                              # restart print spooler
Get-PrintJob -PrinterName "OfficePrinter" | Remove-PrintJob # clear stuck jobs
```

---

## Security Basics

### Endpoint Protection

```bash
# macOS
spctl --status                           # Gatekeeper
csrutil status                           # SIP
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --getglobalstate
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --setglobalstate on

# Linux
sudo ufw enable && sudo ufw default deny incoming && sudo ufw default allow outgoing
```

```powershell
Get-MpComputerStatus | Select AntivirusEnabled, RealTimeProtectionEnabled
Start-MpScan -ScanType QuickScan
Get-NetFirewallProfile | Select Name, Enabled
```

### Phishing Response

```bash
gam update user [email protected] password "$(openssl rand -base64 16)" changepassword on
gam user [email protected] signout             # kill sessions
gam user [email protected] turnoff2sv          # reset MFA
gam user [email protected] show tokens         # check rogue OAuth apps
gam user [email protected] show forwarding     # check attacker persistence
```

### Lost / Stolen Device Protocol

1. **Immediately** -- Remote wipe via MDM or Find My Mac.
2. **Within 15 min** -- Reset password and kill sessions (SSO commands above).
3. **Within 1 hour** -- Rotate API keys and secrets: `gh auth refresh`, delete AWS access keys.
4. **Within 24 hours** -- Review access logs for suspicious activity.

## Related Skills

- [incident-management](../../../compliance/continuity/incident-management/) -- Structured incident handling
- [runbook-creation](../../../compliance/continuity/runbook-creation/) -- Documentation standards