debug-environment_skill

Overview

This skill inspects environment and configuration issues that cause failures in specific contexts. It helps pinpoint missing variables, permission problems, platform differences, and deployment mismatches that lead to runtime errors. The output is a concise investigative report with confidence ratings and actionable next steps.

How this skill works

The skill runs a systematic checklist across configuration, platform, filesystem, and network layers to collect evidence. It compares actual values against expected defaults, validates file formats and permissions, checks runtime and OS compatibility, and tests network reachability and TLS. Findings are categorized with confidence levels (High, Medium, Low, Inconclusive) and include suggested verification steps and remediation actions.

When to use it

• Debugging failures that only occur in a specific environment (staging, prod, CI).
• Investigating missing or incorrect environment variables or config keys.
• Resolving permission, file-access, or symlink-related errors.
• Diagnosing platform-specific crashes or dependency issues.
• Troubleshooting network connectivity, DNS, proxy, or TLS problems.

Best practices

• Start with reproducible, minimal steps and capture environment metadata (OS, runtime, architecture).
• Document expected config defaults and the precedence rules for overrides before testing.
• Gather evidence: logs, exit codes, file listings, permission bits, and sample config files.
• Avoid destructive fixes—apply read-only checks first and only change live config after confirming hypotheses. Use confidence ratings to guide escalation.
• Automate repetitive checks in CI to detect environment drift early.

Example use cases

• CI pipeline failing only on macOS due to case-sensitive filesystem assumptions.
• Production deployment with permission errors preventing service startup due to incorrect user or group.
• Service timeouts in one region caused by a corporate proxy or firewall rule.
• Data parsing differences because of unexpected locale or timezone settings on the host.
• Native dependency failing on ARM architecture in a new cloud instance.