Skill.re
Ai Assisted Troubleshooting Scripts And Runbooks
Hook
Your help desk follows a troubleshooting checklist for "Can't connect to WiFi." Thirty minutes of asking users questions, testing things, and narrowing down the problem. But half the time, the fix is something the user could have done themselves with the right script: remove old WiFi profile, re-scan networks, re-enter password. The other half, it's something your team needs to fix: bad DHCP settings, auth server issue, or interference from another network. Currently, you're paying a help desk person's hourly rate to do work that could be automated. AI can generate diagnostic scripts that ask the right questions in the right order, run the right tests, and direct users to the fix or to your team for escalation. But only if you validate the script first, version-control it, test it in non-prod, and update it when your systems change.
Purpose
This lesson teaches you how to use AI to generate troubleshooting scripts (decision trees that guide diagnostic steps) and runbooks (step-by-step procedures for standard operations). You'll learn how to structure AI prompts so it generates scripts that work in your environment, validate generated scripts before deployment, keep them version-controlled and testable, and iterate when systems change.
Why This Matters for IT Professionals
Troubleshooting and routine operations are often manual. Someone knows the procedure, they execute it, they document it mentally, and next time they do it again. That's fine if it's rare. But when you're doing the same troubleshooting steps 50 times a month, the ROI on automation is obvious.
Scripting and automation let you:
- Move routine work off paid staff: Diagnostic scripts that users can run themselves. Runbooks that non-experts can follow. Means your specialists handle harder problems.
- Reduce human error: A script follows the same steps every time. Humans get tired and skip steps.
- Speed up resolution: A good script finds root cause in 5 minutes instead of 30 minutes of manual troubleshooting.
- Enable escalation: A script that says "you have problem X, here's the fix; if that doesn't work, contact support and tell them X-scenario-1" gives escalation better context.
AI can generate the initial script, but you own validation, testing, and maintenance.
Core Concepts
Key Insight: Diagnostic Scripts Are Decision Trees, Not Procedures
A diagnostic script guides users (or automated tools) through a series of questions and tests to narrow down a problem. It's a decision tree: "Do you see error A or error B? If A, check this. If B, check that."
Example structure for "WiFi not connecting":
- Can you see your WiFi network in the available networks list?
- No: Run [diagnostic to check WiFi adapter]
- Yes: Go to 2
2. Can you enter the password?
- No: Check password, try again
- Yes: Go to 3
3. Does it connect?
- Yes: Test internet, article done
- No: Go to 4
4. Do you see an error message?
- "Can't connect to network" → fix 1
- "Can't connect to server" → fix 2
- "Wrong password" → fix 3
- No error → advanced troubleshooting
AI can generate this tree if you specify the symptoms, common causes, and their fixes upfront.
Key Insight: Environment-Specific Details Make or Break Scripts
A script written for Windows 10 won't work on Windows 11. A PowerShell script for Windows Server 2019 might not work on 2022. A bash script for RHEL 8 has different commands than RHEL 9.
When you ask AI to generate a script, you must specify:
- OS version: "Windows Server 2022 only, not 2019"
- Tools available: "PowerShell 5.1 with no additional modules"
- Network environment: "On a corporate domain, no direct internet access"
- Architecture: "64-bit Windows systems with at least 8GB RAM"
- Known issues: "On this system, the DNS resolver sometimes times out. Account for that."
AI can generate a good script if it knows the constraints. Without them, you get a script that assumes things that aren't true in your environment.
Key Insight: Testing Happens Before Production
Never deploy a script to production without testing it first. Testing means:
- Functional testing: Does the script actually work? Run it on a non-prod system that has the problem it's designed to fix.
- Error testing: What happens when something goes wrong? What if the network is down? What if the service isn't running? Does the script handle it gracefully or hang?
- Edge cases: What if the problem is partially fixed? What if the user interrupted the previous troubleshooting? Does the script still work?
- Syntax testing: Does the script run without errors? Are there typos in command names, file paths, or syntax?
Testing takes time, but skipping it means deploying broken scripts to production.
Key Insight: Version Control Prevents Lost Changes and Enables Rollback
A script that works today might break after a system update. You need to track versions and changes:
- Version number: "WiFi-Diagnostic-v1.1" (major.minor)
- Date: When was this version released?
- Change log: What changed from v1.0 to v1.1?
- Tested on: Which systems, OS versions, hardware?
- Known issues: What scenarios does this script not handle?
Version control lets you rollback if a new version breaks something. It also lets you understand why a change was made (if v1.1 broke something, you can see what changed and revert just that part).
Key Insight: Runbooks Are Linear Procedures, Not Decision Trees
A runbook is different from a diagnostic script. A runbook is step-by-step instructions for a well-defined procedure: "Provision a new user account," "Backup the database," "Upgrade the application."
Runbooks should include:
- Purpose: What does this procedure accomplish?
- Prerequisites: What access, permissions, or tools are needed?
- Time estimate: How long should this take?
- Steps: Numbered, one action per step. Clear, unambiguous.
- Verification: How to confirm each step worked (and what to do if it didn't).
- Rollback: How to undo if something goes wrong.
- Contact info: Who to escalate to if something breaks.
AI can generate runbooks, but you need to be specific about your environment and process.
Key Insight: Feedback and Updates Keep Scripts Accurate
Scripts become stale. Systems change. Your environment changes. You need a process for keeping scripts current:
- Feedback loop: Do operators use this script? Is it helping? Do they hit issues?
- Version schedule: When do you review and update this script? Annually? When you update systems?
- Change process: How do you test and deploy script changes without breaking production?
Without a maintenance process, scripts become technical debt: outdated, confusing, and unreliable.
Practical Use Cases
Use Case 1: Generating a WiFi Troubleshooting Script
Scenario: Your help desk gets 20 "can't connect to WiFi" calls per week. Most are fixable by the user themselves (old WiFi profile, wrong password, airplane mode). You want a script (or step-by-step guide) that users can follow before calling.
What you know about your environment:
- You have one corporate WiFi network called "CompanyWiFi"
- Authentication uses standard WPA2 with AD credentials
- Common issues: old profiles not removed, airplane mode on, credentials changed
- Advanced issues (auth server down) require your team
AI Prompt:
Create a WiFi troubleshooting decision tree for users who can't connect to the corporate WiFi network.
Environment:
- Network name: "CompanyWiFi"
- Authentication: WPA2 with company credentials (username/password same as domain login)
- Operating systems: Windows 10/11 and macOS
- Common issues:
1. Old WiFi profile still cached (authentication fails)
2. Airplane mode is on
3. User entered wrong password
4. WiFi adapter driver needs restart
5. Authentication server temporary issue (our team can fix)
Create a decision tree with numbered questions and branches:
- Each question should be answerable by the user without IT knowledge
- Each answer should lead to either: a fix they can do, a diagnostic command to run, or escalation to IT
- Assume users don't know what a "WiFi driver" is; use simple language
- If the fix doesn't work after they try it, guide them to escalate with context ("We tried X and Y, it still didn't work. Error: Z")
For each fix step, provide:
- Clear instructions (numbered)
- What to expect after each step (success indication)
- What to do if it doesn't work (next troubleshooting step)
For Windows users, include specific UI paths:
- Windows Settings > Network > WiFi (or Ethernet depending on connection type)
- Device Manager paths if driver restart needed
Output as markdown with clear hierarchical structure. Make it scannable (bold key terms, numbered lists).
Include at the end: "Still not connected? Here's what to tell the help desk when you call to help us troubleshoot faster."
What you get: A script that guides users through the most common causes before they contact support. It reduces support volume by identifying the problem clearly and providing context for escalation.
Before AI: You'd spend 2-3 hours writing this (outlining the decision tree, writing clear steps for each fix, testing, formatting).
With AI + 1 hour of review and testing: You have a script you can publish.
What you must do:
- Test every step: Turn WiFi off, forget the network, follow the script, confirm it works.
- Test error scenarios: What if the user doesn't see the expected option? (Different Windows version? Different language setting?)
- Get feedback from help desk: "Do users escalating this issue have better context now? Are they answering these diagnostic questions?"
- Iterate: If users skip a step or get confused, revise the script.
Time saved: 20 calls/week × 15 minutes per call = 300 minutes (5 hours) per week on help desk. If 50% self-resolve with this script, that's 150 minutes (2.5 hours) per week, or 130 hours per year.
Use Case 2: Generating a Server Provisioning Runbook
Scenario: Your team provisions 3-5 new Linux servers per month. The process is manual: allocate IP, set hostname, configure network, join domain, install base packages, configure monitoring. No documented runbook. Each sysadmin does it slightly differently, and mistakes happen. You want AI to help you draft a runbook that all team members can follow.
What you know:
- OS: RHEL 9.2 only
- Network: DHCP with DNS, no manual IPs
- Domain: Active Directory (sssd for auth)
- Base packages: gcc, git, curl, monitoring agent
- Monitoring: Prometheus node exporter
- Provisioning takes 45 minutes, most of which is waiting for updates
AI Prompt:
Create a detailed runbook for provisioning a new RHEL 9.2 Linux server.
Environment:
- OS: RHEL 9.2 (8GB RAM minimum, 50GB disk)
- Network: DHCP for IP, DNS configured via DHCP
- Domain: Active Directory (sssd for auth)
- Base packages to install: gcc, git, curl, net-tools
- Monitoring: Install Prometheus node exporter on port 9100
- After provisioning, add server to Ansible inventory
Runbook structure:
1. Purpose (what this accomplishes, when you'd use this)
2. Prerequisites (what's needed before starting: RHEL media, domain credentials, IP allocation)
3. Time estimate (how long should this take)
4. Steps (numbered, one action per step):
- Including pause points ("Wait for system to boot", "Wait for updates to finish")
- Clear expected output for each step
- How to verify each step succeeded
5. Common issues and fixes (things that might go wrong during provisioning)
6. Post-provisioning checklist (add to monitoring, test domain auth, test sudo, etc.)
7. Rollback (if something goes very wrong, how to revert)
For each step, include:
- The exact command(s) to run
- What success looks like
- What to do if it fails
Special notes:
- The Prometheus node exporter should be installed as a systemd service (so it starts on reboot)
- AD integration uses sssd; provide the exact config
- After domain join, test authentication with a test domain user account
- Some teams prefer to script this (Ansible); note at the end that this could be automated
Output as markdown with:
- Clear numbered steps
- Code blocks for commands
- Inline callouts for warnings ("Don't reboot until updates finish")
- Links or references if this integrates with other runbooks
What you get: A comprehensive runbook that anyone on your team can follow to provision a server consistently.
Before AI: 3-4 hours (documenting from memory, testing steps, writing clearly, reviewing with team).
With AI + 1 hour of team review and testing: A runbook that speeds up provisioning and reduces errors.
What you must do:
- Test the entire runbook end-to-end: provision a test server following the steps exactly as written. Time it.
- Test failure recovery: What if a package fails to install? What if domain join fails? Does the runbook guide you?
- Get team feedback: "Is this clear? Did you hit anything unexpected?"
- Set a maintenance schedule: "Review this runbook annually or when we upgrade RHEL version."
Time saved: 45 minutes per server × (5 servers/month) = 225 minutes/month. If the runbook cuts 15% of that time through clarity and consistency, that's 34 minutes/month (6+ hours/year).
Use Case 3: Updating a Script When Systems Change
Scenario: You have a backup verification script that checks database backup integrity. It's been working for 2 years. You upgrade from PostgreSQL 13 to 15, and the script starts failing because a backup tool changed its output format.
What you do:
- Identify the problem: "Script was written for PostgreSQL 13. Tool output format changed in version 15."
- Update the script:
```
Ask AI: Here's the old script (written for PostgreSQL 13). We've upgraded to PostgreSQL 15, and the backup verification tool changed its output format.
Old tool output (v1.8):
[example output]
New tool output (v2.0):
[example output]
Update the script to parse the new format and produce the same verification output as before.
```
- Test the script: Run it against a database backup. Confirm it correctly verifies the backup.
- Version the change: "backup-verify-v2.1, Updated for PostgreSQL 15 and backup tool v2.0"
- Deploy and monitor: Roll out to all servers. Watch for errors in the first week.
Time spent: 1 hour (identify problem, update script, test, deploy).
Time saved: Prevents 1-2 hours of debugging why backups started failing, or worse, discovering a backup failure after the fact when you actually need to restore.
Examples
Example 1: Simple Decision Tree
AI generates this for "Can't connect to VPN":
- What error do you see when you try to connect?
a) "Connection refused" → Possible VPN server down
- Contact IT support with: "I get 'Connection refused'"
b) "Wrong password" → Password issue
- Reset your VPN password [link to KB article]
- Try connecting again
c) "Timeout" → Network connectivity issue
- Verify you have internet (can you open a web browser?)
- If yes, try connecting again
- If no, fix internet connectivity first
d) "IKE negotiation failed" → Possible VPN config issue
- Verify you're using the latest VPN client [version number]
- If you're using an older version, upgrade first [download link]
- Try connecting again
e) No error, connection just hangs
- Check if VPN client is actually running (Task Manager → Processes)
- If not, launch it and try again
- If it's running, wait 30 seconds for connection to establish
- If still not connecting, kill the process and restart - If none of the above resolved it:
- Note: What error did you see? At what step did it fail?
- Contact IT support with: [error message], [steps you tried], [your OS version]
Your review: "This is good, but we need to add something for Linux users. Also, the VPN server gets rebooted Tuesdays at 2am; should we mention that?"
Your update: Add Linux steps, add note about maintenance windows.
Example 2: Runbook Section Review
AI generates for "User Account Provisioning":
Prerequisites
- Requestor approval (JIRA ticket with approval)
- User details:
- Full name
- Email (company domain)
- Department
- Manager name
- Start date
- System access requirements:
- List of systems they need access to
- Role/position
Your review: "This is missing the 'Security clearance verification' step. In our org, you can't provision accounts without clearance signed off. Also, we've moved to using Active Directory for group memberships, not individual system access."
Your update: Add security clearance requirement, update system access section to reference AD groups.
Example 3: Handling Version Changes
Original script (v1.0):
#!/bin/bash
# Backup verification script
# PostgreSQL 13, Backup Tool v1.8
psql -U backup_user -d production < verify_backup.sql | grep "OK"
New script (v2.1):
#!/bin/bash
# Backup verification script
# PostgreSQL 15, Backup Tool v2.0
# Updated: 2026-04-09 - Changed tool output parsing for v2.0 format
psql -U backup_user -d production < verify_backup.sql | grep "Status: OK"
# Note: Output format changed in Backup Tool v2.0; updated grep pattern
Change log:
- v1.0 → v1.1: Added error handling for missing psql
- v1.1 → v2.0: Updated for PostgreSQL 15 (new psql output format)
- v2.0 → v2.1: Updated for Backup Tool v2.0 (changed output format)
Anti-Patterns
Anti-Pattern 1: Deploying Scripts Without Testing
Don't generate a script and immediately push it to production. Test it in non-prod first. Test error cases. Test with real data.
Anti-Pattern 2: Not Version-Controlling Scripts
Don't let scripts change without tracking what changed and when. Version control (even simple v1, v2, v3) lets you roll back if a change breaks something.
Anti-Pattern 3: Forgetting to Update Scripts When Systems Change
Don't let scripts become stale. When you upgrade a system, update the scripts that interact with it. Set a review cadence.
Anti-Pattern 4: Making Scripts Too Complex
Don't try to handle every edge case in a single script. A script that's 1000 lines long and handles 50 different scenarios becomes unmaintainable. Better to have multiple focused scripts.
Anti-Pattern 5: Not Getting Feedback from Users
Don't assume a script is good because you tested it. Get feedback from people who actually run it. "Is it clear? Did you hit issues? Can we improve it?"
Human Judgment Checkpoints
Before deploying a script or runbook:
Have I tested this end-to-end on a non-prod system? Preferably with real data that matches production.
Does this account for version-specific behavior? If it runs on multiple OS versions, have I tested on all of them?
What happens if something goes wrong mid-way? Does the script handle errors gracefully? Can it be restarted?
Is this documented clearly? Could someone unfamiliar with the system follow this?
Do I have a way to track issues and iterate? How will users report problems? How will you update the script?
Have I tested the rollback? If something goes wrong, can you actually undo it?
Key Takeaways
- Diagnostic scripts are decision trees; runbooks are linear procedures. Structure AI prompts for the right type.
- Environment specifics matter: OS version, tools available, network architecture, architecture. Provide these to AI upfront.
- Testing happens before production: functional testing, error testing, edge cases. Never skip this step.
- Version control scripts and track changes. This lets you roll back if an update breaks something.
- Iterate based on feedback. Use scripts in production, collect feedback, update them. A script that improves based on real-world use becomes more valuable over time.