---
name: error-decoder
description: Diagnose, explain, and suggest fixes for cryptic DevOps error messages from Kubernetes, Terraform, Docker, Helm, CI/CD systems, and cloud providers.
---

## Trigger Phrases
Use this skill when the request contains an error message or failure output that needs interpretation, for example:

- "Why is my pod in CrashLoopBackOff?"
- "Decode this Helm install failure."
- "What does this Terraform provider error mean?"
- "My GitHub Actions job is failing with exit code 1, here's the log."
- "kubectl describe pod shows OOMKilled — what's causing this?"
- "Explain this AWS error and how to fix it."

Do not use this skill for general how-to questions where no error output is present. Use the appropriate generator skill instead.

## Deterministic Execution Flow
Run these stages in order. Do not skip stages.

### Stage 0: Classify Error Origin
Identify the source system before diagnosing:

| System | Common error signals |
|--------|---------------------|
| Kubernetes | Pod phases: `CrashLoopBackOff`, `OOMKilled`, `Pending`, `Evicted`; Events from `kubectl describe` |
| Terraform | Provider errors, state lock errors, `forces replacement`, plan validation failures |
| Docker / containerd | Image pull errors, exit codes, build layer failures |
| Helm | Template rendering errors, hook timeouts, release stuck in `pending-upgrade` |
| GitHub Actions / GitLab CI | Exit codes, timeout errors, runner errors, permission denied |
| Cloud (AWS/GCP/Azure) | API error codes, quota exceeded, IAM permission errors |
| Bash / Shell | Exit codes, `set -e` failures, unbound variable traps |

### Stage 1: Extract Critical Context
Before diagnosing, identify what was provided and ask for anything missing that would change the diagnosis.

**Always required:**
- Full error text (not a summary or screenshot description)
- Tool and version (e.g., `kubectl 1.29`, `terraform 1.7.x`, `helm 3.14`)
- What changed before the error appeared

**Often decisive:**
- For Kubernetes: full `kubectl describe pod <name>` and `kubectl logs <pod>` output
- For Terraform: full `terraform plan` or `terraform apply` output, not just the last line
- For CI/CD: the full job log, not just the failing step

If critical context is missing, ask one focused question. Do not ask for everything at once.

### Stage 2: Diagnose
Apply this diagnostic sequence:

1. **Identify the proximate cause** — what the error is literally saying
2. **Identify the root cause** — what actually triggered it (these are often different)
3. **Check for secondary signals** — warnings or events earlier in the output that point to the real issue
4. **Classify severity** — is this a configuration error, a resource constraint, a permissions issue, a timing/race condition, or a version incompatibility?

Common root-cause patterns by system:

**Kubernetes:**
- `CrashLoopBackOff` → Check container exit code and `kubectl logs`. Exit code 1 = application error. Exit code 137 = OOMKilled. Exit code 143 = SIGTERM (graceful shutdown).
- `OOMKilled` → Memory limit too low or actual memory leak. Check `resources.limits.memory`.
- `Pending` → Node selector, taints/tolerations mismatch, or insufficient cluster resources.
- `ImagePullBackOff` → Image name wrong, registry credentials missing, or private registry not configured in ServiceAccount.

**Terraform:**
- `forces replacement` → Immutable field changed. Confirm with the user before suggesting import or targeted destroy.
- Provider auth errors → Credential chain issue. Check environment variables, profile, or IAM role.
- State lock error → Stale lock from failed run. Verify no concurrent apply before suggesting `force-unlock`.

**Docker:**
- Exit code 137 → OOM kill. Check Docker host memory or container limit.
- Layer cache invalidation errors → Corrupted layer. Suggest `docker build --no-cache`.

### Stage 3: Respond
Structure every diagnosis response as follows:

```
## Error Diagnosis: [Tool] — [Brief error label]

**Root Cause:**
[One clear sentence explaining what's actually wrong]

**Why This Happens:**
[2-4 sentences explaining the mechanism, not just restating the error]

**Fix:**
[Exact commands or config changes needed, with context]

**Verification:**
[How to confirm the fix worked]

**If This Doesn't Resolve It:**
[Next diagnostic step or alternative cause to check]
```

### Stage 4: Escalation Check
After providing the diagnosis, ask:
- Is there additional output (earlier in the log, from a related component) that might reveal a deeper cause?
- Has the fix been applied — should validation steps be walked through?

## Done Criteria
This skill execution is complete only when:
- The source system and error type are explicitly identified.
- Both proximate and root cause are addressed (they are often different).
- A concrete fix is provided with exact commands, not generic advice.
- A verification step is included so the user knows when the fix worked.
- Any dangerous operations (force-unlock, targeted destroy, force-delete) include an explicit warning.