From 4c1f7a2be6efc33f53a2af81ccc0f04bbd76265d Mon Sep 17 00:00:00 2001
From: Andy Baran <andy.baran@hashicorp.com>
Date: Mon, 6 Jul 2026 13:54:07 -0400
Subject: [PATCH] Be explicit about accessing state in ways that are token
 efficient.

---
 .../skills/terraform-search-import/SKILL.md   | 22 ++++++++++++++++++
 .../skills/refactor-module/SKILL.md           | 23 ++++++++++++++++++-
 2 files changed, 44 insertions(+), 1 deletion(-)

diff --git a/terraform/code-generation/skills/terraform-search-import/SKILL.md b/terraform/code-generation/skills/terraform-search-import/SKILL.md
index 4a39391..e4392f7 100644
--- a/terraform/code-generation/skills/terraform-search-import/SKILL.md
+++ b/terraform/code-generation/skills/terraform-search-import/SKILL.md
@@ -302,6 +302,28 @@ import {
 }
 ```
 
+## Verifying Imported State
+
+After running `terraform apply` to import resources, verify what actually landed in state.
+Prefer the documented, stable, and more token-efficient commands over reading the raw state
+file:
+
+```bash
+# Confirm resources are now managed (also confirms addresses)
+terraform state list
+
+# Inspect resolved attribute values for imported resources
+terraform show -json | jq '.values.root_module.resources[] | {address, type, name}'
+```
+
+`terraform show -json` requires providers to be installed (`terraform init`), since it
+renders values against provider schemas. **Fall back to the raw state
+(`terraform state pull` / `terraform.tfstate`) only when** providers aren't available and
+`init` can't run, you need only coarse info (addresses, outputs, `serial`/`lineage`), or you
+must avoid executing Terraform. Avoid parsing the raw version-4 state format as a stable
+interface. **Note:** state contains sensitive values in plaintext in every format — never
+echo state contents into logs or output.
+
 ## Best Practices
 
 ### Query Design
diff --git a/terraform/module-generation/skills/refactor-module/SKILL.md b/terraform/module-generation/skills/refactor-module/SKILL.md
index 7d58f67..ed6af2a 100644
--- a/terraform/module-generation/skills/refactor-module/SKILL.md
+++ b/terraform/module-generation/skills/refactor-module/SKILL.md
@@ -22,7 +22,7 @@ The agent will analyze existing Terraform code and systematically refactor it in
 ## Prerequisites
 - Existing Terraform configuration to refactor
 - Understanding of resource dependencies
-- Access to current state file (for migration planning)
+- Access to inspect current state via `terraform state list` / `terraform show -json` (for migration planning)
 - Knowledge of module registry patterns
 
 ## Input Parameters
@@ -277,6 +277,27 @@ module "vpc" {
 
 ### 4. State Migration
 
+#### Inspecting Current State
+Before writing `moved` blocks or `state mv` commands, inspect the current state to map
+existing resource addresses. Prefer the documented, stable, and more token-efficient
+commands over reading the raw state file:
+
+```bash
+# Enumerate current resource addresses (the inputs for `moved` / `state mv`)
+terraform state list
+
+# Inspect resolved attribute values when you need them
+terraform show -json | jq '.values.root_module'
+```
+
+`terraform show -json` requires providers to be installed (`terraform init`), since it
+renders values against provider schemas. **Fall back to the raw state
+(`terraform state pull` / `terraform.tfstate`) only when** providers aren't available and
+`init` can't run, you need only coarse info (addresses, outputs, `serial`/`lineage`), or you
+must avoid executing Terraform. Avoid parsing the raw version-4 state format as a stable
+interface. **Note:** state contains sensitive values in plaintext in every format — never
+echo state contents into logs or output.
+
 #### Generate Migration Plan
 ```hcl
 # migration.tf