arn-infra-change-spec

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:
2. Check for IaC files in the project (.tf, Pulumi., cdk.json, .bicep, fly.toml, docker-compose.yml, Kubernetes manifests, platform configs)
3. Check for resource manifests (active-resources.json, tooling-manifest.json)
4. Check for existing provider configuration (.arness/infra/providers.md)

1. 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)."

1. Extract infrastructure context from artifacts:
2. Read the IaC files to identify resources being created, modified, or configured
3. Read provider configuration for environment and provider details
4. Read any existing specs or briefs in the infra specs directory

1. 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 sufficient detail.

Intermediate: Ask 3-5 structured questions covering the key areas:

• "Which resources are affected and what operations (create/modify/destroy)?"
• "Which environments does this change target?"
• "Are there rollback constraints or compliance requirements?"
• "What is the expected cost impact?"

Beginner: Walk through each area with explanations:

• "Let's start with what needs to change. Can you describe the resources involved? (For example: a database, a load balancer, a DNS record...)"
• "Which environments will this affect? (For example: just development, or also staging and production?)"
• "If something goes wrong, how would you want to undo this change?"
• "Are there any budget limits or compliance rules to consider?"

Step 3: Load References and Analyze

Read ${CLAUDE_PLUGIN_ROOT}/skills/arn-infra-change-spec/references/infra-change-spec-template.md for the spec template.

Read ${CLAUDE_PLUGIN_ROOT}/skills/arn-infra-change-spec/references/blast-radius-guide.md for blast radius classification.

Using the change description (from Step 2a or 2b), perform initial analysis:

1. Classify blast radius per environment using the blast-radius-guide classifications (None/Contained/Broad/Critical)
2. Identify affected resources with provider, action (create/modify/destroy), and environment scope
3. Assess rollback complexity based on the types of changes involved
4. Estimate cost impact direction (increase/decrease/neutral) and rough magnitude

Step 4: Invoke Agents for Deep Analysis

If application context is available (the change is driven by an application feature, or cross-project artifacts exist):

Invoke the arn-infra-request-analyzer agent via the Task tool, passing the model from .arness/agent-models/infra.md as the model parameter (see plugins/arn-infra/skills/arn-infra-ensure-config/references/ensure-config.md "Dispatch convention" for fallback). Context:

--- CHANGE CONTEXT ---
[change description from Step 2a or 2b]
--- END CHANGE CONTEXT ---

--- INFRASTRUCTURE CONFIG ---
Providers: [from ## Arness]
Environments: [from ## Arness]
Experience level: [derived from user profile]
--- END INFRASTRUCTURE CONFIG ---

--- INSTRUCTIONS ---
Analyze the infrastructure implications of this change. Identify all affected
resources, dependencies between resources, and potential impacts on existing
infrastructure. Focus on what needs to change and what could break.
--- END INSTRUCTIONS ---

Always invoke the arn-infra-cost-analyst agent for preliminary cost estimation:

--- CHANGE CONTEXT ---
[change description including identified resources and operations]
---