Terraform Optimizer

Audit a Terraform codebase, report what is unsafe, brittle or expensive and why, agree a plan, then change it. Order: evidence, approval, edits. State and apply changes can destroy infrastructure; nothing is applied before approval.

Workflow

1. Scope (quick)

• Map the repo: root modules, environments, backends, workspaces, providers, modules, state files, CI apply path and cloud accounts. Record Terraform/OpenTofu and provider versions.
• Run python <skill-dir>/scripts/audit.py <repo-root> -- static scan of .tf/.tfvars/lockfiles/state for EOL versions, unpinned providers/modules, missing backends/locking, hardcoded secrets, public network/storage, IAM wildcards, destructive settings and plan-safety gaps, with file:line evidence. Use --json to post-process.
• Classify the pain: state/backend, plan/apply safety, drift, module structure, security/compliance, provider/version upgrades, or cost. Ask which hurts if unclear.
• Read references/tooling.md once: what can be measured here (terraform validate/plan, plan JSON, terraform graph, cost, policy scans).

2. Audit

The script finds cheap leads; you find the rest by reading the root module, backend, variables, state and the CI plan/apply path. Load only what applies:

Measure, never guess. Run terraform init -backend=false, validate, fmt -check, a read-only plan in the target workspace/account, and a policy/scan pass. A clean plan is not proof of safety; review the diff, state and apply path.

Mark each finding Confirmed (plan/state/config/policy evidence) or Suspected (needs measuring).

3. Report

Fill assets/report-template.md, save it as TERRAFORM_OPTIMIZATION_REPORT.md in the repo root, and show the user. Five-line summary, findings table by impact/effort/risk, then per-finding detail (evidence, why it hurts, fix, state/plan impact, rollback). Group near-duplicates.

4. Plan -- then stop for approval

Use plan mode: EnterPlanMode (load with ToolSearch if deferred), write the plan, present with ExitPlanMode; if unavailable show it in chat and wait for an explicit "go". Structure:

1. Quick wins -- pin versions/providers/modules, add lockfile, remote backend/locking, remove hardcoded secrets, close public ports/ACLs, enable encryption/deletion protection, add lifecycle/prevent_destroy, fix plan-safety scripts. Low risk.
2. Structural -- split root modules/environments, introduce modules/composition, move state with moved/import, adopt workspaces or separate states, add policy/tests/CI gates, centralize providers/tags. Name each state/plan change.
3. Heavy -- Terraform/OpenTofu major upgrade, backend migration, provider major, module extraction/refactor, account/region split, Terragrunt/Stacks adoption. Separately approved with state backup and rollback. Each step: files/state touched, expected plan diff, how to verify, how to roll back.

5. Fix

Only approved items, in small groups. After each: terraform fmt -check, validate, plan in the target workspace, policy/scan, and review the diff. Never run apply as part of an audit without explicit approval. If a change alters state addresses, provider auth, IAM, network exposure or data stores, stop and ask; take a state backup first.

6. Verify and wrap up

Re-run the same checks: plan diff/no-op, policy/scan findings, state lineage/lock, drift, apply time, resource count and cost estimate. State plainly what could not be measured. End with deferred items and one suggested next step.

Principles

• State is the source of truth. Remote, encrypted, locked, backed up and access-controlled.
• Plan is a review artifact. Save/show it; apply the exact approved plan, not a fresh one.
• Pin everything. Terraform/OpenTofu, providers, modules and lockfiles; upgrades are deliberate.
• Least privilege and no public defaults. IAM, security groups, buckets, databases.
• Move, don't recreate. moved/import before address changes; never hand-edit state.
• Secrets are not variables in git. Secret manager/CI env, sensitive/ephemeral values, encrypted state.
• Modules need contracts. Inputs/outputs/versions/README; avoid god modules and remote-state coupling.
• Test and gate. terraform test, validation, policy/scan and a PR plan.
• Measure cost and drift. A cheap plan can create expensive, drifting infrastructure.