---
name: guided-troubleshooting
description: Create interactive troubleshooting workflows that walk customers through diagnostic steps to resolve issues without agent intervention. Use when building decision-tree diagnostics, creating step-by-step troubleshooting flows, designing guided resolution paths, implementing symptom-based diagnostics, or reducing support ticket volume through self-service troubleshooting. Triggers on phrases like "guided troubleshooting", "diagnostic workflow", "troubleshooting tree", "step-by-step fix", "diagnostic flow", "self-service troubleshooting", "decision tree support", "interactive diagnostic".
---

# Guided Troubleshooting Workflows

Walk customers through diagnostic steps to resolve issues without agent intervention.

## Workflow

### Troubleshooting Workflow Design

Trigger: New product issue pattern; recurring support category; quarterly workflow review:

1. **Issue identification**: Analyze support tickets to identify top troubleshooting categories (top 10 issue types representing 60–70% of tickets); categorize by product area and complexity.
2. **Root cause mapping**: For each issue, map all known causes (typically 5–15 per issue type); rank by frequency (%); determine diagnostic questions that isolate each cause.
3. **Decision tree design**: Build branching logic — start with broad question; narrow down through successive yes/no questions; each leaf node = specific fix.
4. **Fix scripting**: For each leaf node, write clear fix steps (numbered, with screenshots/GIFs); include "Did this work?" checkpoint; add escalation path if fix fails.
5. **Auto-data collection**: Integrate with product APIs to auto-collect diagnostics (account status, error logs, API health) — reduces manual steps by 30–50%.
6. **QA testing**: Test with 50+ real customer scenarios; validate path efficiency (average steps to resolution ≤ 6); verify 100% of known causes are covered.
7. **Launch and monitor**: Deploy to self-service portal and chatbot; track resolution rate (target 55–70%); monitor drop-off points; iterate monthly.
8. **Continuous improvement**: Add new branches from escalated tickets; retire low-usage paths; optimize question order based on analytics.

### Troubleshooting Workflow Template

```
TROUBLESHOOTING WORKFLOW — LOGIN ISSUES (EXAMPLE)
===================================================

Issue: "I can't log in to my account"

Step 1: Can you reach the login page?
  Yes → Go to Step 2
  No → Check internet connection; verify URL (portal.company.com); clear browser cache; try incognito mode
       Did this work? Yes → RESOLVED | No → Step 1b

Step 1b: What error do you see on the login page?
  "Page not found" → Verify correct URL; contact support if persistent
  "Connection timeout" → Check firewall settings; try different network
  "500 Internal Error" → Our system may be down; check status page; wait 15 min and retry
  Other → ESCALATE (collect error screenshot)

Step 2: What happens when you enter your credentials?
  "Password incorrect" → Step 3
  "Account locked" → Step 5
  "Error: [specific code]" → Step 6
  "Loads but nothing happens" → Clear cookies; disable browser extensions; try different browser
  "Account not found" → Verify email address; check for typos; try account recovery

Step 3: Have you tried password reset?
  Yes → Step 4
  No → Click "Forgot Password"; enter email; check inbox/spam for reset link; click link; set new password
       Did this work? Yes → RESOLVED | No → Step 4

Step 4: Is the reset email arriving?
  Yes → Click link within 24 hours; check browser pop-up blockers
  No → Check spam/junk folder; add support@company.com to contacts; try different email address
       If email on file is wrong → Update email via account recovery form
       Did this work? Yes → RESOLVED | No → ESCALATE

Step 5: Account locked — unlock process
  Click "Unlock Account" below login form
  Enter verification code sent to email/phone
  Set new password
  Did this work? Yes → RESOLVED | No → ESCALATE (security review needed)

Step 6: Check specific error code
  Error 1001: Session expired → Log out completely; clear cookies; log back in
  Error 1002: Invalid credentials → Verify username (not email); reset password
  Error 1003: Account suspended → Contact billing (payment issue); call support line
  Error 1004: MFA required → Open authenticator app; enter 6-digit code
  Other error → ESCALATE (collect error code + screenshot)

Escalation: If all steps fail, auto-create ticket with:
  - All steps attempted (with customer answers)
  - Browser/OS info (auto-detected)
  - Account ID and login email
  - Time of last attempt
  - Route to: Technical Support Queue (Priority: Medium)
```

### Workflow Analytics Dashboard

```
TROUBLESHOU BING WORKFLOW PERFORMANCE METRICS
================================================

Workflow: Login Issues
Last updated: Monthly

Volume Metrics:
  Total sessions: 1,250/month
  Self-resolved: 68% (850 sessions)
  Escalated to agent: 32% (400 sessions)
  Abandoned mid-flow: 12% (150 sessions)

Efficiency Metrics:
  Average steps to resolution: 4.2 (target: ≤ 6)
  Average time to resolution: 3.5 minutes (target: ≤ 5)
  Most efficient path: Step 1 → Step 2 → Step 3 → Reset (62% of resolutions)
  Least efficient path: Step 1 → Step 1b → Step 2 → Step 6 → Escalate (8% of sessions)

Drop-off Analysis:
  Step 1 drop-off: 5% (low — question is clear)
  Step 2 drop-off: 8% (acceptable)
  Step 3 drop-off: 18% (HIGH — password reset step too complex; simplify)
  Step 4 drop-off: 15% (HIGH — email troubleshooting needs better guidance)

Optimization Recommendations:
  1. Simplify Step 3: Add direct reset link instead of instructions
  2. Add Step 1.5: Quick "Are you using the right email?" check
  3. Add video guide for Step 4 (email troubleshooting)
  4. New branch: "Forgot which email I used?" → account recovery by phone number

ROI:
  Tickets deflected: 850/month (× 5 min agent time = 70.8 agent-hours saved/month)
  Agent cost savings: $2,124/month (at $30/hour fully-loaded)
  Annual savings: $25,488
  Customer satisfaction: 4.3/5.0 (resolved without waiting for agent)
```

## Edge Cases

- **Ambiguous symptoms** (customer describes issue in vague terms):
  - Example: "My account isn't working"
  - Strategy: Start with broad triage questions; use visual aids (screenshots of expected vs. actual); ask for screenshots
  - Question design: Use "What are you trying to do?" instead of "What error do you see?"
  - Fallback: If unable to narrow after 3 questions, escalate with all attempted paths

- **Multi-component issues** (root cause spans multiple systems):
  - Example: Integration failure — could be API, network, or configuration
  - Strategy: Parallel diagnostic branches; check each component independently; present combined results
  - Auto-checks: API status endpoint; network connectivity test; configuration validation tool
  - Complexity limit: If 3+ components involved, escalate to engineer with full diagnostic report

- **Outdated troubleshooting paths** (product changed but workflow not updated):
  - Detection: Resolution rate drops below baseline; customer feedback "this didn't work" increases
  - Prevention: Tie workflow updates to product release notes; automated flag when KB article referenced is updated
  - SLA: Update workflows within 48 hours of product change affecting covered issues
  - Review: Monthly review of all active workflows against current product version

- **Frustrated customer experience** (customer already tried basic steps before reaching bot):
  - Detection: Customer says "I already tried that" or sentiment analysis shows frustration
  - Adaptation: Skip common steps; ask "What have you already tried?" (checkbox selection); jump to advanced steps
  - Proactive: At start, offer "Already tried the basics?" shortcut to advanced troubleshooting
  - Empathy: When frustration detected, add empathetic language: "I understand this is frustrating. Let's try something different."

- **Regulatory/compliance troubleshooting** (security-related issues):
  - Example: Suspected unauthorized access, data breach
  - Rule: NEVER guide through security investigation; escalate immediately to security team
  - Immediate action: Auto-lock account (if confirmed breach); notify customer; create P1 ticket to security
  - Documentation: Log all troubleshooting steps for forensic analysis
  - Communication: Use approved incident communication templates only

## Integration Points

- **Help desk platforms**: Zendesk, Freshdesk — ticket auto-creation on escalation; conversation history transfer
- **Product APIs**: Custom endpoints for account status, error logs, API health checks
- **Chatbot platforms**: Intercom, Drift, Dialogflow — embed troubleshooting flows in conversational UI
- **Knowledge base**: Zendesk Guide, Confluence — link troubleshooting steps to detailed articles
- **Customer data**: Salesforce, HubSpot — account tier, plan details, usage history
- **Analytics**: Mixpanel, Amplitude — step-by-step funnel tracking; drop-off analysis
- **Screen recording**: Loom, Lookback — customers can record screen for context
- **Error tracking**: Sentry, Bugsnag — correlate customer errors with known issues
- **Status page**: Atlassian Statuspage — auto-reference system status during troubleshooting
- **Data warehouse**: Snowflake — historical troubleshooting data for pattern analysis