Site Scout

Section 2: Reconnaissance Checks

Run each check independently. If one fails, log the failure and continue to the next.

Check 1: WordPress Debug Log

Look for recent error entries in the WordPress debug log.

# Check if debug.log exists and get recent entries
DEBUG_LOG=$(ssh $SSH_OPTS "${USER}@${HOST}" \
  "if [ -f '${WP_PATH}/wp-content/debug.log' ]; then
    echo 'EXISTS'
    wc -l < '${WP_PATH}/wp-content/debug.log'
    tail -50 '${WP_PATH}/wp-content/debug.log'
  else
    echo 'NOT_FOUND'
  fi" 2>&1)

Output fields:

• debug_log.exists: boolean
• debug_log.line_count: number (if exists)
• debug_log.recent_entries: last 50 lines (if exists)
• debug_log.error_patterns: extracted unique error types

Check 2: PHP Error Log

Find and read the PHP error log location.

# Get PHP error log path and recent entries
PHP_ERROR_LOG=$(ssh $SSH_OPTS "${USER}@${HOST}" \
  "php -r 'echo ini_get(\"error_log\");' 2>/dev/null" 2>&1)

if [ -n "$PHP_ERROR_LOG" ] && [ "$PHP_ERROR_LOG" != "" ]; then
  PHP_ERRORS=$(ssh $SSH_OPTS "${USER}@${HOST}" \
    "if [ -f '$PHP_ERROR_LOG' ]; then tail -30 '$PHP_ERROR_LOG'; else echo 'NOT_READABLE'; fi" 2>&1)
fi

Output fields:

• php_error_log.path: string
• php_error_log.recent_entries: last 30 lines
• php_error_log.readable: boolean

Check 3: Recently Modified Files

Identify files changed in the last 7 days within wp-content (where custom code and plugins live).

# Find recently modified PHP files in wp-content
RECENT_FILES=$(ssh $SSH_OPTS "${USER}@${HOST}" \
  "find '${WP_PATH}/wp-content' -name '*.php' -mtime -7 -type f 2>/dev/null | head -50" 2>&1)

# Count total and break down by directory
RECENT_COUNT=$(echo "$RECENT_FILES" | grep -c '\.php$' || echo "0")

Output fields:

• recent_modifications.files: array of file paths
• recent_modifications.count: number
• recent_modifications.by_directory: breakdown (plugins/, themes/, mu-plugins/, etc.)

Check 4: wp-config.php Environment Indicators

Read key configuration values that affect diagnostic approach.

# Extract environment-relevant config values (NOT credentials)
CONFIG_VALUES=$(ssh $SSH_OPTS "${USER}@${HOST}" \
  "grep -E '(WP_DEBUG|WP_DEBUG_LOG|WP_DEBUG_DISPLAY|WP_ENVIRONMENT_TYPE|DISALLOW_FILE_EDIT|WP_CACHE|MULTISITE)' '${WP_PATH}/wp-config.php' 2>/dev/null || \
   grep -E '(WP_DEBUG|WP_DEBUG_LOG|WP_DEBUG_DISPLAY|WP_ENVIRONMENT_TYPE|DISALLOW_FILE_EDIT|WP_CACHE|MULTISITE)' '${WP_PATH}/../wp-config.php' 2>/dev/null" 2>&1)

Output fields:

• config.wp_debug: boolean
• config.wp_debug_log: boolean
• config.wp_debug_display: boolean
• config.environment_type: string (production/staging/development/local)
• config.disallow_file_edit: boolean
• config.wp_cache: boolean
• config.multisite: boolean

Check 5: PHP Environment

Get PHP version and key settings that affect site behavior.

# PHP version and settings
PHP_INFO=$(ssh $SSH_OPTS "${USER}@${HOST}" \
  "php -r 'echo json_encode([
    \"version\" => PHP_VERSION,
    \"memory_limit\" => ini_get(\"memory_limit\"),
    \"max_execution_time\" => ini_get(\"max_execution_time\"),
    \"upload_max_filesize\" => ini_get(\"upload_max_filesize\"),
    \"post_max_size\" => ini_get(\"post_max_size\"),
    \"display_errors\" => ini_get(\"display_errors\")
  ]);' 2>/dev/null" 2>&1)

Output fields:

• php.version: string
• php.memory_limit: string
• php.max_execution_time: string
• php.upload_max_filesize: string
• php.display_errors: string

Check 6: Active Plugins and Theme (WP-CLI)

If WP-CLI is available, get the active plugin and theme list.

if [ "$WP_CLI_PATH" != "null" ] && [ -n "$WP_CLI_PATH" ]; then
  # Active plugins
  ACTIVE_PLUGINS=$(ssh $SSH_OPTS "${USER}@${HOST}" \
    "${WP_CLI_PATH} plugin list --status=active --format=json --path='${WP_PATH}'" 2>&1)

  # Active theme
  ACTIVE_THEME=$(ssh $SSH_OPTS "${USER}@${HOST}" \
    "${WP_CLI_PATH} theme list --status=active --format=json --path='${WP_PATH}'" 2>&1)

  # Plugin count
  PLUGIN_COUNT=$(echo "$ACTIVE_PLUGINS" | jq 'length' 2>/dev/null || echo "unknown")
fi

Output fields:

• plugins.active: array of {name, version, update_available}
• plugins.count: number
• theme.active: {name, version}
• wp_cli_available: boolean

Check 7: HTTP Status Check

Verify the site is responding and check for common issues.

# HTTP status check (from remote server to avoid CDN/firewall differences)
HTTP_STATUS=$(ssh $SSH_OPTS "${USER}@${HOST}" \
  "curl -sI -o /dev/null -w '%{http_code}' --max-time 10 '${SITE_URL}'" 2>&1)

# Check for maintenance mode
MAINTENANCE_MODE=$(ssh $SSH_OPTS "${USER}@${HOST}" \
  "test -f '${WP_PATH}/.maintenance' && echo 'true' || echo 'false'" 2>&1)

Output fields:

• http.status_code: number
• http.maintenance_mode: boolean

Check 8: Disk Usage

Overview of space consumption in wp-content subdirectories.

DISK_USAGE=$(ssh $SSH_OPTS "${USER}@${HOST}" \
  "du -sh '${WP_PATH}/wp-content'/*/ 2>/dev/null | sort -rh | head -10" 2>&1)

# Total wp-content size
TOTAL_SIZE=$(ssh $SSH_OPTS "${USER}@${HOST}" \
  "du -sh '${WP_PATH}/wp-content' 2>/dev/null" 2>&1)

Output fields:

• disk.wp_content_total: string (e.g., "2.3G")
• disk.by_directory: array of {directory, size}

Section 3: Output

Write the structured scout report to memory/{site}/scout-report.json:

{
  "site": "{site-name}",
  "scouted_at": "{ISO8601 timestamp}",
  "duration_seconds": 15,
  "checks_completed": 7,
  "checks_failed": 1,
  "environment": {
    "php_version": "8.2.14",
    "wp_debug": true,
    "environment_type": "production",
    "multisite": false,
    "maintenance_mode": false,
    "http_status": 200,
    "wp_cli_available": true
  },
  "recent_activity": {
    "modified_files_7d": 12,
    "modified_files_by_area": {
      "plugins": 8,
      "themes": 3,
      "mu-plugins": 1
    },
    "debug_log_exists": true,
    "debug_log_lines": 4521,
    "recent_errors": ["Fatal error: Allowed memory size exhausted", "Warning: Cannot modify header information"]
  },
  "resources": {
    "php_memory_limit": "256M",
    "wp_content_size": "2.3G",
    "largest_directories": [
      {"directory": "uploads", "size": "1.8G"},
      {"directory": "plugins", "size": "320M"}
    ]
  },
  "plugins": {
    "active_count": 14,
    "active_list": ["woocommerce", "yoast-seo", "contact-form-7"]
  },
  "alerts": [
    "WP_DEBUG is enabled in production",
    "12 PHP files modified in last 7 days",
    "Debug log has 4521 lines — active error logging"
  ],
  "failed_checks": [
    {"check": "php_error_log", "reason": "PHP error log path not set"}
  ]
}

Alert Generation

Generate alerts from scout data to highlight things that warrant attention:

Section 4: Error Handling

SSH Connection Failure

If the SSH connection fails entirely, return a minimal scout report:

{
  "site": "{site-name}",
  "scouted_at": "{timestamp}",
  "checks_completed": 0,
  "checks_failed": 8,
  "error": "SSH connection failed: {error_message}",
  "alerts": ["Cannot connect to server — all reconnaissance skipped"],
  "failed_checks": [{"check": "all", "reason": "SSH connection failed"}]
}

Individual Check Failure

If a single check times out or errors, record it in failed_checks and continue:

# Example: wrap each check with error handling
CHECK_RESULT=$(ssh $SSH_OPTS "${USER}@${HOST}" "..." 2>&1)
CHECK_EXIT=$?

if [ $CHECK_EXIT -ne 0 ]; then
  # Record failure, continue to next check
  FAILED_CHECKS+=("{\"check\": \"check_name\", \"reason\": \"$CHECK_RESULT\"}")
fi

Timeout Handling

Each SSH command should have a reasonable timeout to prevent hanging:

# Use ConnectTimeout in SSH options (already set to 10s)
# For long-running commands, use timeout wrapper:
ssh $SSH_OPTS "${USER}@${HOST}" "timeout 15 find '${WP_PATH}/wp-content' -name '*.php' -mtime -7 -type f 2>/dev/null | head -50"

Section 5: Integration with Diagnostic Planning

The scout report informs the /investigate command's diagnostic planning (Section 5 of COMMAND.md).

How scout data influences skill selection:

Notes

• All checks are read-only — never modify anything on the remote server
• SSH credentials are never logged or included in output
• Scout report is saved to memory/ which is gitignored
• Check duration target: entire scout should complete in < 30 seconds
• If WP-CLI is unavailable, skip WP-CLI-dependent checks (plugin list, theme list) and note in report
• Scout data is informational — it guides diagnostics but doesn't replace them