# IaC Patch Safety Guide

Use this reference when editing CloudFormation, SAM, CDK, Terraform, or AWS-focused IaC files to correct defects while staying repo-scoped.

## What people get wrong

The lazy story is:

> IaC patching is safe because it is only a file change.

Wrong. A small IaC diff can delete data, replace resources, widen IAM, expose networks, or break rollback once applied.

Common bad assumptions:

- Syntax validation catches dangerous changes.
- Resource replacement is acceptable unless production says otherwise.
- Deleting a property is safer than setting it explicitly.
- IAM wildcard is temporary and harmless.
- Security group changes are easy to reason about by inspection.
- Terraform plan/change set is optional for small patches.

## High-risk diff classes

Flag these before editing or recommending apply:

- resource deletion or replacement
- IAM action/resource/principal broadening
- security group/NACL/route/public exposure changes
- KMS key policy, secret, certificate, or data-store retention changes
- database, queue, bucket, stream, or backup lifecycle changes
- cross-account trust or SCP/permission boundary changes
- drift-sensitive changes where live state may differ from repo

## Minimum safe workflow

1. Identify IaC framework and target environment.
2. Inspect existing style and patch only the requested defect.
3. Classify blast radius and high-risk diff class.
4. Run static validation: template lint, synth, format, schema, or validate.
5. If live execution is requested later, require plan/change-set/drift evidence first.
6. Provide rollback: revert diff, prior parameter value, previous template, or state-safe rollback path.
7. Keep live apply/deploy/destroy out of scope unless separately approved.

## Verification targets

- `cfn-lint`, `aws cloudformation validate-template`, `sam validate`
- `cdk synth`, `cdk diff`
- `terraform fmt`, `terraform validate`, `terraform plan` when applicable
- CloudFormation replacement/delete indicators from change sets
- drift detection output for existing stacks
- policy validation for IAM/security-sensitive changes
- project-specific tests and schema checks

## When to push back

Push back if the user asks to:

- apply/deploy immediately after a repo patch
- skip plan/change-set because the diff is small
- use wildcard IAM to unblock validation
- delete stateful resources without backup/retention proof
- change production networking without rollback path
- “clean up” unrelated IaC while fixing one issue

# Official sources

Use this reference only when you need source grounding for AWS service behavior or the detailed source list.

## AWS documentation

Use these as starting points, not as proof of the user's live AWS state:
- https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/best-practices.html
- https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-changesets-samples.html
- https://docs.aws.amazon.com/cdk/v2/guide/home.html
- https://docs.aws.amazon.com/prescriptive-guidance/latest/choose-iac-tool/cloudformation.html

## Grounding rule

Official documentation explains AWS service behavior. It does not prove the user's current account, Region, quota, resource configuration, IAM boundary, pricing, entitlement, or operational state. Prefer read-only AWS MCP or CLI evidence, repository evidence, or sanitized user-provided evidence for current-state claims.

## Current MCP/documentation refresh (2026-06-02)

Service facts from official docs:
- CloudFormation best practices include validating templates, creating change sets before updating stacks, using stack policies, logging CloudFormation calls with CloudTrail, using drift detection, configuring rollback triggers, and applying least privilege.
- Change-set examples show that template edits, parameter changes, added/removed resources, and replacement fields can alter blast radius in different ways.

Sampled live evidence:
- Read-only regional availability sampling reported AWS CloudFormation as `isAvailableIn` in `us-east-1`, `us-west-2`, `eu-west-1`, and `ap-southeast-1`.
- Sampled APIs `CloudFormation+ValidateTemplate`, `CloudFormation+CreateChangeSet`, and `CloudFormation+DetectStackDrift` were reported `isAvailableIn` in those regions.

Review implications:
- Patch execution must stay repo-scoped unless explicitly approved for live mutation; every patch needs minimal diff, validation output, expected plan/change-set effect, and rollback instructions.
- Do not claim production safety from local syntax validation alone; replacement/delete risk and live drift require stronger evidence.

# Safety checklist

- Do not ask for or print secrets, credentials, access tokens, private keys, account numbers, or customer identifiers.
- Keep edits minimal and reversible.
- Do not perform live cloud mutation by default.
- Surface rollback implications and missing validation explicitly.
- Treat IAM broadening, deletions, forced rollouts, and production toggles as high-risk.

# Workflow and output contract

Use this reference for full write-capable AWS patch work.

## Workflow

1. Classify the repo-side correction.
2. Confirm the target files and blast radius.
3. Make the smallest reversible edit.
4. Run local validators or syntax checks.
5. Report exact files changed, validation results, and rollback path.

## Guardrails

- Repo write access is allowed.
- Live AWS mutation is out of scope by default.
- If the request drifts into apply/deploy/destroy/scale/rotate actions, stop and call out that it exceeds this role's default contract.