Terraform Specialist
Structured investigation for Terraform codebases. Five phases: gather context,
diagnose, design, recommend, verify.
Arguments
$0 — module path, workspace context, or problem description. Required.
Phase 1: Context Gathering
- Identify the scope: module, workspace, or full repo.
- Glob for Terraform files:
find . -name "*.tf" | sort
find . -name "*.tfvars" | sort
find . -name ".terraform.lock.hcl" | sort
- Check backend and provider configuration:
grep -r "backend" . --include="*.tf" -l
grep -r "required_providers" . --include="*.tf" -l
- Check for existing state:
terraform workspace list
terraform state list
Phase 2: Diagnosis
Module structure:
# Check module inputs/outputs surface
grep -r "variable\|output\|locals" . --include="*.tf" -l
terraform validate
State health:
terraform state list
terraform state show <resource>
terraform plan -detailed-exitcode
Provider locks:
cat .terraform.lock.hcl
terraform providers
Test coverage:
find . -name "*_test.go" -o -name "*.tftest.hcl" | sort
Phase 3: Design / Root-Cause Analysis
Map symptoms to causes:
| Symptom |
Common Causes |
Check |
| Plan shows unexpected replace |
ForceNew attribute changed, ID drift |
terraform state show + provider docs |
| State drift |
Manual console change, import not run |
terraform refresh + terraform plan |
| Module coupling |
Outputs passed through too many layers |
Count cross-module variable chains |
| Provider version conflict |
Lock file pinned differently per module |
.terraform.lock.hcl comparison |
count vs for_each bug |
Resource renamed on index change |
Switch to for_each with stable keys |
Cite file:line for every finding.
Phase 4: Recommendations
Output findings in priority order:
[CRITICAL] <title>
Resource: <address or file:line>
Issue: <one sentence>
Evidence: <plan output or code snippet>
Fix: <specific change, with HCL diff if applicable>
Trade-off: <alternative and its downside, if meaningful>
Order: CRITICAL → WARNING → INFO.
Phase 5: Verification
After fixes are applied:
- Re-run
terraform validate — no errors.
- Run
terraform plan — confirm zero unexpected changes.
- For state moves:
terraform state list before and after.
- For module refactors: run tests if present (
terraform test or go test ./...).
- Confirm
.terraform.lock.hcl is committed and unchanged.
Reference Docs
| File |
When to use |
modules.md |
Module design, variable/output surface, coupling |
state-management.md |
Backends, state mv, import, drift remediation |
workspaces.md |
Workspace-per-env vs stack-per-env trade-offs |
testing.md |
Unit tests, integration tests, tftest |
providers.md |
Provider config, version pinning, aliases |
import-patterns.md |
terraform import, import blocks, bulk import |
1---2# dotbabel:generated projection=sha256:289bc0fd87630f02df9f5e9442bc8d9dc67dddf42f6a092bc5a15ab29b52392c source=skills/terraform-specialist/SKILL.md — do not edit directly3allowed-tools: Read Grep Glob Bash4argument-hint: <module path, workspace, or problem description>5description: |6 Deep-dive Terraform architecture review, module design, state management, and migration. Use for structured investigations of Terraform workspaces, provider configuration, module coupling, import workflows, and test coverage. Triggers on: "Terraform audit", "module review", "state management", "Terraform import", "workspace design", "provider config review", "Terraform testing".7name: terraform-specialist-38metadata:9 source: https://skillmd.com/skills/kaiohenricunha/terraform-specialist-310---1112# Terraform Specialist1314Structured investigation for Terraform codebases. Five phases: gather context,15diagnose, design, recommend, verify.1617## Arguments1819- `$0` — module path, workspace context, or problem description. Required.2021---2223## Phase 1: Context Gathering24251. Identify the scope: module, workspace, or full repo.262. Glob for Terraform files:27 ```bash28 find . -name "*.tf" | sort29 find . -name "*.tfvars" | sort30 find . -name ".terraform.lock.hcl" | sort31 ```323. Check backend and provider configuration:33 ```bash34 grep -r "backend" . --include="*.tf" -l35 grep -r "required_providers" . --include="*.tf" -l36 ```374. Check for existing state:38 ```bash39 terraform workspace list40 terraform state list41 ```4243---4445## Phase 2: Diagnosis4647**Module structure:**4849```bash50# Check module inputs/outputs surface51grep -r "variable\|output\|locals" . --include="*.tf" -l52terraform validate53```5455**State health:**5657```bash58terraform state list59terraform state show <resource>60terraform plan -detailed-exitcode61```6263**Provider locks:**6465```bash66cat .terraform.lock.hcl67terraform providers68```6970**Test coverage:**7172```bash73find . -name "*_test.go" -o -name "*.tftest.hcl" | sort74```7576---7778## Phase 3: Design / Root-Cause Analysis7980Map symptoms to causes:8182| Symptom | Common Causes | Check |83| ----------------------------- | --------------------------------------- | -------------------------------------- |84| Plan shows unexpected replace | `ForceNew` attribute changed, ID drift | `terraform state show` + provider docs |85| State drift | Manual console change, import not run | `terraform refresh` + `terraform plan` |86| Module coupling | Outputs passed through too many layers | Count cross-module variable chains |87| Provider version conflict | Lock file pinned differently per module | `.terraform.lock.hcl` comparison |88| `count` vs `for_each` bug | Resource renamed on index change | Switch to `for_each` with stable keys |8990Cite `file:line` for every finding.9192---9394## Phase 4: Recommendations9596Output findings in priority order:9798```99[CRITICAL] <title>100Resource: <address or file:line>101Issue: <one sentence>102Evidence: <plan output or code snippet>103Fix: <specific change, with HCL diff if applicable>104Trade-off: <alternative and its downside, if meaningful>105```106107Order: CRITICAL → WARNING → INFO.108109---110111## Phase 5: Verification112113After fixes are applied:1141151. Re-run `terraform validate` — no errors.1162. Run `terraform plan` — confirm zero unexpected changes.1173. For state moves: `terraform state list` before and after.1184. For module refactors: run tests if present (`terraform test` or `go test ./...`).1195. Confirm `.terraform.lock.hcl` is committed and unchanged.120121---122123## Reference Docs124125| File | When to use |126| --------------------- | ------------------------------------------------ |127| `modules.md` | Module design, variable/output surface, coupling |128| `state-management.md` | Backends, state mv, import, drift remediation |129| `workspaces.md` | Workspace-per-env vs stack-per-env trade-offs |130| `testing.md` | Unit tests, integration tests, tftest |131| `providers.md` | Provider config, version pinning, aliases |132| `import-patterns.md` | `terraform import`, import blocks, bulk import |