supraj.dev Search

Security / REFERENCE BLUEPRINT

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.

Explore the workflowCheck prerequisites
DESIGN INTENT

This is documentation for a proposed implementation. No automation runs from this page. Commands, configuration, output and timing are illustrative; package availability and measured performance have not been verified here.

THE LOOP / 5 STEPS

From the first signal to the final action.

  1. 01

    TRIGGER

    terraform plan in CI (any PR)

  2. 02

    PARSE

    structured plan JSON — resources, actions, attributes

  3. 03

    REASON · AI

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

  4. 04

    HARD RULE

    any destroy of stateful resource → 🚨 block-level warning

  5. 05

    ACT

    single PR comment, updated in place on re-plan

01 / USAGE

How the intended workflow fits together

  1. 01

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

  2. 02

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

  3. 03

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

02 / CONFIGURATION

Read the configuration contract

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

Illustrative configuration. Adapt only after verifying the implementation, schema and service permissions.

# 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 / EVIDENCE

What an output could look like

This authored example describes the intended result format. It is not evidence that a live run occurred.

🚨 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

04 / IMPLEMENTATION REFERENCE

Review the setup sketch

The original command sketch is preserved for design context. It is not a verified installation recipe. Confirm that the package or repository exists and review its implementation before running anything.

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