Tfappfix

Terraform Debugging (/tfappfix)

Pragmatic terraform debugging for a 2-person team. No enterprise overhead.

Philosophy: What This Skill Is NOT

Skip these enterprise patterns - you are 2 people:

• Complex policy checks (Sentinel/OPA) - just review the plan
• Multi-workspace orchestration - you have dev/prod, that is enough
• Drift detection dashboards - just run terraform plan
• Checkpoint files - terraform state IS the checkpoint
• 4-agent planning - talk to each other instead

Terraform already provides:

• State management (do not reinvent it)
• Change detection (plan -detailed-exitcode)
• Locking (do not build another layer)
• Dependency resolution

This skill focuses on:

• Diagnosing why plan/apply failed
• Common Azure provider issues
• Safe state manipulation when needed
• Getting CI green again

Triggers

• /tfappfix, "fix terraform", "debug infra", "why did apply fail"
• "plan is failing", "state is locked", "terraform error"

The 80/20 of Terraform Debugging

Most terraform issues are solved by reading the error message carefully.

Workflow

Phase 0: CONTEXT
  - Identify the failing stack
  - Get the error (from user, CI logs, or local run)

Phase 1: DIAGNOSE
  - Run fmt, validate, plan locally
  - Check state lock status if relevant
  - Check Azure resource status if apply failed

Phase 2: FIX
  - Apply code changes
  - State ops require user confirmation

Phase 3: VERIFY
  - Plan shows expected changes
  - Push to trigger CI

Phase 0: Get Context

Find out:

1. Which stack? (Look for directories with main.tf or *.tf files)
2. What is the error? (CI log, local error, or symptom)
3. Plan or apply failure?

If user provides a GitHub Actions run URL:

gh run view <run-id> --log-failed

Phase 1: Diagnose

Always start here - run the basics:

cd <stack-path>  # directory containing main.tf

# 1. Format check
terraform fmt -check -recursive

# 2. Validate (fast, no backend)
terraform init -backend=false
terraform validate

# 3. Full plan (if validate passes)
terraform init
terraform plan -out=debug.tfplan

Check state lock (if plan hangs): For Azure Blob backend, check lease status with az storage blob show.

Check Azure resource status (if apply failed mid-way):

az resource list -g <resource-group> --query "[].{name:name, state:properties.provisioningState}" -o table

Phase 2: Fix

Error: State Lock

For Azure Blob backend:

# Check lease status
az storage blob show --container-name <container> --name <state-file> --account-name <storage> --query "properties.lease"

# Break lease (ASK USER FIRST)
az storage blob lease break --container-name <container> --name <state-file> --account-name <storage>

Safety gate: Always ask user before breaking a lock.

Error: Resource Already Exists

Resource exists in Azure but not in state.

⚠️ CRITICAL: 99% of cases should DELETE, not import.

DEFAULT ACTION (do not ask, just do this):

1. Ask user to DELETE the resource in Azure Portal or CLI
2. Re-run terraform to create it fresh under Terraform management

# Example: delete a role assignment
az role assignment delete --ids "<resource-id>"

# Example: delete a generic resource
az resource delete --ids "<resource-id>"

IMPORT IS ALMOST NEVER CORRECT. Only consider import when ALL of these are true:

1. The resource has existed for a long time (months/years, not hours/days)
2. The resource contains irreplaceable data or configuration that cannot be recreated
3. The resource is managed in a different terraform repo OR was created manually before IaC

If you believe import is appropriate, you MUST:

1. Stop and ask the user with ALL of these details:
   • Why you believe this qualifies as a rare import case
   • What the resource is and how long it has existed
   • The exact import command you would run
   • The risk: import can cause state corruption if the resource config doesn't match
2. Wait for explicit "yes, import it" confirmation
3. Note: terraform import is BLOCKED by the command guard - user must run manually

DO NOT ask about import for resources created in the last few days. Just delete and recreate.

Error: Resource Not Found (Drift)

Resource in state but deleted from Azure:

# Remove from state - ASK USER FIRST
terraform state rm <resource.address>

Error: Provider / API Error

Error: Module/Provider Version

terraform providers
terraform init -upgrade

Phase 3: Verify

# Local plan should show expected changes
terraform plan

# Push to trigger CI
git add <files>
git commit -m "fix(terraform): <description>"
git push

# Monitor CI
gh run watch

Finding Stacks

Discover terraform stacks in your repo:

# Find all directories with terraform files
find . -name "*.tf" -type f | xargs dirname | sort -u

# Or look for backend configurations
grep -r "backend" --include="*.tf" -l

Understand dependencies:

• Check terraform_remote_state data sources for cross-stack references
• Check module sources for shared modules
• Apply order: shared/platform stacks first, then application stacks

Safety Rules

BLOCKED (cannot run via Claude - user must run manually):

• terraform import — blocked by command guard
• terraform state rm — blocked by command guard
• terraform apply — blocked by command guard
• terraform destroy — blocked by command guard

Ask user before:

• Breaking state locks
• Suggesting user run terraform import (see "Resource Already Exists" - 99% should DELETE instead)
• Operations on production stacks
• Any -force flags

Proceed without asking:

• terraform fmt
• terraform validate
• terraform plan
• terraform init
• Code changes to .tf files
• Committing and pushing

Azure Authentication

# Check auth
az account show

# Login if needed
az login

# Set subscription
az account set -s <subscription-id>

For terraform:

export ARM_SUBSCRIPTION_ID=$(az  account show --query id -o tsv)
export ARM_TENANT_ID=$(az account show --query tenantId -o tsv)

Error Message Decoder

When to Escalate

Talk to your teammate (not Claude):

• Production outage
• Security-related changes
• Billing/cost decisions
• Architectural changes
• Anything you are not sure about

This skill is for:

• Getting a failing plan/apply to pass
• Understanding error messages
• Safe state manipulation with confirmation
• Quick fixes, not redesigns