kaiohenricunha 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 listbefore and after. - For module refactors: run tests if present (
terraform testorgo test ./...). - Confirm
.terraform.lock.hclis 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 |