IAC · AI

TF Plan Explainer

Nobody reads a 400-line terraform plan, and that's how the wrong RDS instance gets destroyed. This loop compresses every plan into a ranked, plain-English summary as a PR comment — destruction first, cosmetics last — with hard rules the AI cannot override.

TRIGGER

terraform plan in CI (any PR)

PARSE

structured plan JSON — resources, actions, attributes

REASON · AI

rank by risk: destroy > replace > modify > tag-only

HARD RULE

any destroy of stateful resource → 🚨 block-level warning

ACT

single PR comment, updated in place on re-plan

01 — INSTALL

# .github/workflows/plan.yml — add after terraform plan
- uses: supraj/tf-explainer@v2
  with:
    plan: tfplan.json
    anthropic_key: ${{ secrets.ANTHROPIC_KEY }}

02 — CONFIGURE

Runs as a CI step. Stateful-resource rules are regex, not AI — they can't be talked out of firing.

# explainer.yaml
risk_rules:            # deterministic, run before AI
  - match: 'aws_db_instance.*destroy'
    level: block
  - match: 'aws_s3_bucket.*destroy'
    level: block
summary:
  model: claude-haiku
  max_lines: 8
  order: [destroy, replace, modify, create, tags]

03 — HOW IT WORKS

Consumes the plan's JSON output in CI — it never runs terraform itself and needs no cloud credentials.

Deterministic risk rules run first: destroying anything stateful produces a block-level warning no matter what the AI thinks.

The AI writes the summary under a hard line budget, ordered by risk. Re-plans update the same comment — no PR spam.

04 — EXAMPLE OUTPUT

🚨 DESTROYS aws_db_instance.orders-replica
   (plan replaces it due to engine_version bump)
⚠  replaces 2 × aws_launch_template (new AMI)
·  modifies 6 security-group rules (ingress CIDRs)
·  14 changes are tag-only

47 resources in plan · 3 need real review