remote-troubleshoot

name

remote-troubleshoot

description

Structured remote server troubleshooting workflow that follows investigation-only practices until user approval. Use when Claude needs to diagnose issues on remote SSH-accessible servers including k8s clusters, bare metal, and containerized services. Covers service/port access problems, configuration issues, service startup failures, and performance/resource issues. Emphasizes creating helper scripts on remote server, obtaining user approval before fixes, script-based repairs, and generating comprehensive analysis reports.

Remote Server Troubleshooting

Overview

Provides a structured workflow for troubleshooting issues on remote servers with emphasis on:

• Investigation-only approach until user approval
• Creating reusable helper scripts on remote server
• Script-based fixes for reproducibility
• Comprehensive analysis and resolution reports

Investigation Workflow

Phase 0: Information Gathering

Before starting any investigation, gather:

1. Remote Server Access

   • Server address/IP
   • SSH method (sshpass, keys, etc.) and credentials
   • Remote user

2. Problem Description

   • What is the exact issue?
   • When did it start?
   • What service/component is affected?

3. Context

   • Environment (k8s, bare metal, containerized)
   • Relevant config file locations
   • Recent changes

Phase 1: Initial Verification (Read-Only)

CRITICAL: Do NOT make any changes without user approval

Validate the reported issue actually exists:

sshpass -p<password> ssh -o StrictHostKeyChecking=no user@host 
ssh user@host 
ssh user@host 
ssh user@host