---
name: terraform-explainer
description: Explain, review, and audit Terraform HCL code — modules, resources, data sources, locals, outputs, and plans — for correctness, security, and production safety.
---

## Trigger Phrases
Use this skill when the request involves understanding or auditing Terraform code:

- "Explain what this Terraform module does."
- "Review this Terraform plan for anything destructive."
- "Does this create any public-facing resources?"
- "What variables are required vs. optional in this module?"
- "Is this Terraform state management setup correct?"
- "Flag anything in this plan that could cause downtime."
- "Audit this IAM policy block for over-permissioned roles."

Do not use this skill for writing new Terraform from a plain-English description — use `terraform-generator` for that.

## Deterministic Execution Flow

### Stage 0: Classify Request Mode

| Mode | User intent | Deliverable |
|------|-------------|-------------|
| `explain` | Understand what the code does | Plain-English walkthrough by section |
| `audit` | Find misconfigurations or risks | Severity-labeled findings list |
| `plan-review` | Review a `terraform plan` output | Flag destructive, unexpected, or high-risk operations |
| `security-check` | IAM, security groups, public resources | Access-focused findings |
| `variable-map` | Which variables are required and what they do | Structured variable reference |

### Stage 1: Identify Input Type
Determine what was provided:

| Input type | How to handle |
|------------|---------------|
| Single `.tf` file | Review the file in isolation, note cross-file dependencies |
| Multiple `.tf` files | Review holistically; note what's missing (e.g., `variables.tf` not provided) |
| Module directory | Identify `main.tf`, `variables.tf`, `outputs.tf` roles |
| `terraform plan` output | Focus on change summary — additions, modifications, destructions, `forces replacement` |
| `terraform state show` | Explain what's currently managed and any drift risk |

Ask for additional files if the review requires context that's clearly missing (e.g., referencing `var.foo` when `variables.tf` wasn't provided).

### Stage 2: Explain Checklist
For `explain` mode, walk through:

1. **What cloud resources will be created/managed** — summarize in plain English
2. **Required vs. optional variables** — table format
3. **What's non-obvious** — default values that deviate from cloud defaults, unusual resource configurations
4. **Cross-resource dependencies** — what depends on what, and why it matters for destroy order
5. **Outputs** — what values are exported and who uses them

### Stage 3: Audit Checklist
For `audit` and `security-check` modes:

**Networking / Public exposure:**
- [ ] `ingress 0.0.0.0/0` or `::/0` on security groups without justification
- [ ] S3 buckets with `acl = "public-read"` or `block_public_acls = false`
- [ ] RDS/databases with `publicly_accessible = true`
- [ ] Load balancers or API Gateways without WAF or access logging
- [ ] `associate_public_ip_address = true` on EC2 instances without necessity

**IAM:**
- [ ] `Action = "*"` or `Resource = "*"` in IAM policies (wildcard over-permission)
- [ ] IAM roles with `Principal = "*"` (allows any AWS account to assume)
- [ ] Missing `Condition` blocks on sensitive IAM policies
- [ ] Cross-account trust without explicit account ID allowlist

**State and secrets:**
- [ ] Remote backend configured (local state is a risk in team environments)
- [ ] State backend uses encryption at rest
- [ ] No plaintext secrets in `.tf` files or `terraform.tfvars`
- [ ] Sensitive outputs marked `sensitive = true`

**Production safety:**
- [ ] `prevent_destroy = true` on stateful resources (databases, S3 buckets)
- [ ] `deletion_protection` enabled on RDS, EKS clusters
- [ ] `force_delete` or `skip_final_snapshot` not silently set on databases

### Stage 4: Plan Review Checklist
For `plan-review` mode, specifically check:

| Signal | What to flag |
|--------|-------------|
| `forces replacement` | Immutable field change — causes destroy + recreate. Flag every instance. |
| `destroy` actions | Any resource being destroyed — confirm intent |
| `Plan: X to add, Y to change, Z to destroy` | Flag if Z > 0 |
| Large additions (>10 resources) | Confirm scope is expected |
| `known after apply` on critical fields | Flag if a security group ID or DB endpoint is unknown — may affect dependent resources |

Plan review response format:
```
## Plan Review Summary
- Resources to add: N
- Resources to change: N
- Resources to destroy: N ⚠️

## High-Risk Operations
[List every destroy/replacement with explanation of impact]

## Unexpected Changes
[Flag anything that wasn't obviously implied by the described change]

## Safe to Apply?
[Yes / No / Yes with caveats — explain why]
```

## Done Criteria
- Input type is identified (single file, module, plan output).
- `explain` mode produces a plain-English resource summary and variable table.
- `audit` mode uses severity labels and covers networking, IAM, state, and production safety.
- `plan-review` mode explicitly lists every `forces replacement` and `destroy` action.
- Public exposure findings are always labeled CRITICAL.
- `terraform plan` review ends with an explicit safe-to-apply recommendation.