/arn-infra-change-spec

name: arn-infra-change-spec
description: >-
  This skill should be used when the user says "infra change spec",
  "infrastructure change", "specify infrastructure change", "change spec",
  "arn infra spec", "describe infra change", "what infrastructure needs to change",
  "infra spec", "spec this infra change", "write infra spec",
  "infrastructure change specification", "create infra change spec",
  "upgrade to pipeline", "convert to pipeline", or wants to iteratively develop
  an infrastructure change idea into a well-formed specification through guided
  conversation, or wants to upgrade existing interactive IaC artifacts into the
  structured change pipeline.
version: 1.0.0

Arness Infra Change Spec

Develop an infrastructure change idea into a well-formed specification through iterative conversation, aided by the `arn-infra-request-analyzer` and `arn-infra-cost-analyst` agents. This is a conversational skill that runs in normal conversation (NOT plan mode). The primary artifact is an **infrastructure change specification** written to the project's infra specs directory that captures affected resources, blast radius, environment scope, rollback requirements, compliance constraints, and cost impact. The spec then informs plan creation via `/arn-infra-change-plan`.

This skill supports two entry paths:

• **Fresh:** Guide the user through an iterative conversation to develop the change from scratch
• **Upgrade from interactive:** Accept existing IaC artifacts or resource manifests produced by interactive skills (define, containerize, deploy) and build a structured spec around them

Pipeline position: arn-infra-init -> arn-infra-wizard (Full Pipeline) -> [arn-infra-change-spec] -> arn-infra-change-plan -> arn-infra-save-plan -> arn-infra-execute-change -> arn-infra-review-change -> arn-infra-document-change

Prerequisites

Read `## Arness` from the project's CLAUDE.md. If no `## Arness` section exists or Arness Infra fields are missing, inform the user: "Arness Infra is not configured for this project yet. Run `/arn-infra-wizard` to get started — it will set everything up automatically." Do not proceed without it.

Check the **Deferred** field. If `Deferred: yes`, inform the user: "Infrastructure is in deferred mode. Change specification is not available until infrastructure is fully configured. Run `/arn-infra-assess` to un-defer." Stop.

Extract:

• **Infra specs directory** -- path where INFRA_CHANGE_*.md specs are stored (default: `.arness/infra-specs`)
• **Experience level** -- derived from user profile. Read `~/.arness/user-profile.yaml` (or `.claude/arness-profile.local.md` if it exists — project override takes precedence). Apply the experience derivation mapping from `${CLAUDE_PLUGIN_ROOT}/skills/arn-infra-ensure-config/references/experience-derivation.md`. If no profile exists, check for legacy `Experience level` in `## Arness` as fallback.
• **Providers** -- which cloud providers are configured
• **Environments** -- which environments exist and their promotion order
• **Cost threshold** -- budget threshold for cost impact warnings

If `Infra specs directory` is not configured, use the default `.arness/infra-specs`. If the directory does not exist, create it: `mkdir -p <infra-specs-dir>`.

---

Workflow

Step 1: Determine Entry Path

Analyze the user's trigger message and project state to determine which entry path to follow.

**Upgrade detection:** Check for signals that the user wants to upgrade existing interactive work to the pipeline:

• User explicitly says "upgrade to pipeline", "convert to pipeline", or "upgrade from interactive"
• User references existing IaC artifacts: "I already defined infrastructure", "I used arn-infra-define", "upgrade my existing infrastructure"
• Existing IaC files are present and the user references them

**If upgrade signals are detected:** Go to Step 2a (Upgrade Path).

**If no upgrade signals:** Go to Step 2b (Fresh Path).

---

Step 2a: Upgrade from Interactive Path

This path accepts existing IaC artifacts produced by interactive skills and builds a structured change spec around them.

1. **Locate existing artifacts:**

• Check for IaC files in the project (`.tf`, `Pulumi.*`, `cdk.json`, `*.bicep`, `fly.toml`, `docker-compose.yml`, Kubernetes manifests, platform configs)
• Check for resource manifests (`active-resources.json`, `tooling-manifest.json`)
• Check for existing provider configuration (`.arness/infra/providers.md`)

2. **Present findings to the user:**

"I found the following existing infrastructure artifacts:

| Artifact | Type | Provider | Path | |----------|------|----------|------| | ... | IaC/Config/Manifest | ... | ... |

I'll build a change specification around these. This captures the change formally so it can go through the structured pipeline (plan, execute, review, document)."

3. **Extract infrastructure context from artifacts:**

• Read the IaC files to identify resources being created, modified, or configured
• Read provider configuration for environment and provider details
• Read any existing specs or briefs in the infra specs directory

4. **Proceed to Step 3** with the extracted context as the initial change description. Skip the iterative idea capture -- the artifacts define what is changing.

---

Step 2b: Fresh Path

Guide the user through developing the change idea from scratch.

Ask the user to describe their infrastructure change. Accept anything from a single sentence to a detailed description. Do not require a specific format.

If the user already provided the change idea in their trigger message (e.g., "infra change spec: migrate the database to a managed service"), use that directly without asking again.

Acknowledge the idea with a brief restatement to confirm understanding.

**Prompt questions to fill gaps** (adapt to experience level):

**Expert:** Ask targeted questions only for genuinely missing information. Trust the user to provide sufficie