Troubleshooter for Support — Claude Code Plugin

Version: 1.0.0 Type: Claude Code Plugin (skills + sub-agents + WordPress knowledge base)

A complete Claude Code plugin that gives WordPress support teams AI-powered troubleshooting — without needing developer expertise. It reads your plugin's actual GitHub codebase, analyzes debug logs, runs a structured 14-point WordPress diagnostic, and produces a report that explains why an issue happened and how to fix it.

Once installed, /troubleshoot is available in every Claude Code session on your machine — no project setup, no per-ticket configuration.

---

What It Does

When you run /troubleshoot, it walks through a structured 8-phase session:

1. Checks for incomplete sessions — offers to resume if one was interrupted
2. Runs intake — collects issue description, plugin/WordPress/PHP versions, hosting environment
3. Analyzes in parallel:
   • Parses your debug.log (hard limit: 300 lines to prevent context overflow)
   • Reads relevant sections of the GitHub codebase via GitHub MCP
   • Optionally inspects a staging site via Playwright MCP
4. Runs quality gates — deterministic checks that verify every finding is grounded in real data before proceeding
5. Identifies root cause — with specific code file references from your plugin's actual codebase
6. Generates a structured report — shown in full in chat AND saved to _internal/reports/

---

Requirements

Requirement	Notes
Claude Code	Must be installed and logged in
GitHub Personal Access Token	contents: read scope on your plugin repo
Node.js	Required for MCP server installation
macOS / Linux: Bash	Built-in
Windows: Git for Windows	git-scm.com — includes Git Bash

MCP servers (installed automatically during setup):

• GitHub MCP — reads your plugin's GitHub repository (required)
• Playwright MCP — browser-based site testing on staging environments (optional)

---

Installation

Step 1 — Clone or download this repository

git clone https://github.com/nsebastian-web/troubleshooter-for-support.git
cd troubleshooter-for-support

Or download the ZIP from GitHub and extract it.

Step 2 — Run the setup wizard

macOS / Linux:

bash scripts/setup.sh

Windows — Option A (easiest): Double-click scripts/setup.bat. It opens Git Bash and runs setup automatically.

Windows — Option B: VS Code terminal

1. Open the folder in VS Code
2. Open the terminal (Ctrl+`` backtick)
3. Click the dropdown next to + and select Git Bash
4. Run bash scripts/setup.sh

Windows — Option C: PowerShell

.\scripts\setup.ps1

Windows prerequisite: Git for Windows must be installed first.

Step 3 — What the setup wizard does (5 steps, fully interactive)

The wizard handles everything — no manual file editing:

Step	What happens
1/5	Installs plugin files, skills, and sub-agents to ~/.claude/
2/5	Prompts for your GitHub PAT, validates it against the API, stores it securely
3/5	Registers one or more plugin GitHub repositories
4/5	Installs GitHub MCP (required) and optionally Playwright MCP
5/5	Repository indexing runs automatically on your first /troubleshoot session

Token storage by OS:

• macOS: Stored in Keychain — never in any file
• Windows: Written to ~/.bash_profile as an environment variable
• Linux: You add it to ~/.bashrc or ~/.zshrc (wizard shows the exact line)

Step 4 — Start troubleshooting

Open any Claude Code session and type:

/troubleshoot

---

Commands

/troubleshoot — Start a troubleshooting session

The main command. Guides you through the full diagnostic flow — intake → analysis → root cause → report. Supports session resume if interrupted.

/troubleshoot-setup — Configure or update

Run this to:

• Add a new GitHub repository
• Update your GitHub token (tokens expire — default is 90 days)
• Install or reinstall GitHub MCP or Playwright MCP
• Re-index a repository after major code changes

---

Providing Logs

The plugin asks for log excerpts. Do not paste the entire file — the plugin enforces a 300-line limit to avoid context issues.

Use these commands to extract the relevant section:

# Last 300 lines of WordPress debug.log:
tail -300 /path/to/wp-content/debug.log

# Errors from today only:
grep "$(date +'%d-%b-%Y')" /path/to/wp-content/debug.log

# All fatal errors:
grep "PHP Fatal error" /path/to/wp-content/debug.log

If WP_DEBUG isn't enabled, the plugin will guide you through enabling it safely:

// Add to wp-config.php (before "That's all, stop editing!"):
define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false ); // Keeps errors out of the site frontend

---

Live Site Testing (Playwright)

The plugin can launch a browser to inspect the site directly. Important guidelines:

• Only use on staging or test environments — never on live customer sites without permission
• CloudFlare, WAFs, and bot protection may block the automated browser
• The plugin detects this automatically and falls back gracefully if blocked
• The setup wizard asks whether to install Playwright MCP; you can always add it later via /troubleshoot-setup

---

Report Format

Every session produces a structured report like this:

# Troubleshooting Report — [Issue Title]
Session: 2026-02-26-14-30-a7k2 | Opened by: [name] | Plugin: [plugin name]

## Issue Summary
## Environment Details
## Investigation Checklist (what was checked)
## Root Cause — WHY This Is Happening
  • Code Reference: includes/backup/class-backup.php:312
  • Trigger Condition: [what causes it]
  • Impact: [what the customer experiences]
## Recommended Fix
  • Immediate Fix (support team action)
  • Permanent Fix (developer required)
## What Had Already Been Tried
## Escalation Recommendation
## Evidence (log excerpts + code snippets)

Reports are saved to _internal/reports/ with a timestamp and session ID. Paste them into FreshDesk, HelpScout, Zendesk, or wherever you track tickets.

---

Session Resume

If a session is interrupted (timeout, connection drop), the next /troubleshoot detects it and asks:

I found an incomplete troubleshooting session:
  Issue: backup-failing-on-migration
  Last active: today at 14:30
  Progress: Completed through Phase 2

Resume it, or start fresh? (resume / new)

All phase progress is saved to _internal/sessions/ — nothing is lost.

---

Security

• GitHub token is stored in macOS Keychain (or an environment variable on Windows/Linux) — never written to any config file
• config/.troubleshooter.json contains only repository metadata and settings — no tokens
• _internal/ is gitignored — session data, reports, and logs are never committed
• Customer log data should be sanitized before sharing (remove passwords, API keys before pasting logs)

---

Updating the Plugin

To pull the latest version without losing your configuration:

bash scripts/setup.sh --update

This re-installs all plugin files, skills, and sub-agents while preserving your existing config/.troubleshooter.json.

---

Uninstalling

bash scripts/uninstall.sh

Removes all skills, agents, MCP server entries, and stored tokens. Your _internal/ folder (session logs and reports) is preserved unless you choose to delete it during the uninstall prompt.

---

Supported WordPress Environments

The plugin has environment-specific diagnostic checklists for:

• Standard WordPress — cPanel, Plesk, shared hosting
• WP Engine — including EverCache, SFTP-only restrictions, and portal settings
• Kinsta — including Kinsta cache layers, Nginx rules, and MyKinsta settings
• WordPress Multisite — network admin vs. subsite isolation, domain mapping

---

Architecture

Plugin source (this repo)              Installed to ~/.claude/
─────────────────────────              ──────────────────────
skills/troubleshoot/SKILL.md    →      ~/.claude/skills/troubleshoot/SKILL.md
skills/troubleshoot-setup/      →      ~/.claude/skills/troubleshoot-setup/SKILL.md

agents/ts-*.md (7 agents)       →      ~/.claude/agents/ts-*.md

skills/, knowledge/, templates/
config/, _internal/             →      ~/.claude/skills/troubleshooter-for-support/

Sub-agents (7 specialists):

Agent	Model	Role
ts-intake-agent	Sonnet	Collects issue details across 6 structured groups
ts-repo-reader	Sonnet	Builds file map, runs targeted keyword searches on GitHub codebase
ts-log-analyzer	Sonnet	Parses debug.log, matches against 37+ error patterns
ts-site-tester	Sonnet	Browser testing via Playwright (staging only)
ts-code-detective	Opus	Root cause analysis with verified code references
ts-qa-checker	Haiku	Deterministic quality gate enforcement (not AI-on-AI)
ts-issue-reporter	Sonnet	Final structured report generation

Quality gates (4 blocking, 1 advisory):

Gate	What it checks
QG-1	Intake complete — all required fields present
QG-2	Analysis grounded in real data — no hallucinated findings
QG-3	Code references verified against actual file map
QG-4	Report has all required sections
TONE	Clarity and tone review (advisory only)

---

Troubleshooting the Plugin Itself

# Check installation and config:
bash scripts/validate-config.sh

# Check Claude Code version:
claude --version

# Re-run setup to fix any issues:
bash scripts/setup.sh

---

File Structure (repo)

troubleshooter-for-support/
├── SKILL.md                           # Root plugin manifest (not user-invocable)
├── README.md
├── skills/
│   ├── troubleshoot/SKILL.md          # /troubleshoot command
│   └── troubleshoot-setup/SKILL.md    # /troubleshoot-setup command
├── agents/
│   ├── ts-intake-agent.md
│   ├── ts-repo-reader.md
│   ├── ts-log-analyzer.md
│   ├── ts-site-tester.md
│   ├── ts-code-detective.md
│   ├── ts-qa-checker.md
│   └── ts-issue-reporter.md
├── knowledge/
│   ├── wp-troubleshooting-checklist.md
│   ├── wp-error-patterns.md           # 37+ error patterns
│   ├── wp-log-formats.md
│   ├── wp-common-fixes.md
│   └── wp-environments/
│       ├── standard.md
│       ├── wp-engine.md
│       ├── kinsta.md
│       └── multisite.md
├── templates/
│   ├── session-plan.md
│   ├── intake-form.md
│   └── report-output.md
├── config/
│   └── .troubleshooter.example.json   # Example only — live config is gitignored
├── _internal/                         # Runtime data — gitignored
│   ├── sessions/
│   ├── repo-index/
│   └── reports/
└── scripts/
    ├── setup.sh                       # Full setup wizard (run this first)
    ├── install.sh                     # File installer (called by setup.sh)
    ├── uninstall.sh
    ├── validate-config.sh
    ├── setup.bat                      # Windows: double-click to run
    └── setup.ps1                      # Windows: PowerShell alternative