Terraform Atomic Commit Skill

When to Use This Skill

Use this Skill in Terraform / Terragrunt repos (for example terraform-modules/ and infrastructure/) when you want:

• /terraform:pre-commit – to actively fix formatting + lint issues and get the working tree into a clean, reviewable state.
• /terraform:atomic-commit – to enforce atomicity of the staged diff, run the repo’s quality gates, and propose a commit message (no AI signatures).

Example Prompts

• “Run /terraform:pre-commit and fix all issues in the files shown by git status (fmt, validate, docs).”
• “Use /terraform:atomic-commit to confirm the staged diff is atomic and ready; propose a commit message.”
• “We’re in a Terragrunt repo: enforce formatting, skip any apply, and run read-only validation checks where possible.”

Modes

This Skill behaves differently based on how it is invoked:

• pre-commit mode:
  • Actively applies changes to make the working tree/staged files conform to repo standards.
  • Runs auto-fixers and focused validation.
  • Does not propose or drive a commit.
• atomic-commit mode:
  • Runs everything from pre-commit mode.
  • Enforces atomicity of staged changes.
  • Requires all gates to be green.
  • Proposes a commit message without any AI signatures.

Severity Tags

• [BLOCKING] – must fix before merge/commit (broken fmt/validate, dangerous workflow, non-atomic diff).
• [SHOULD_FIX] – strongly recommended before merge (lint warnings, missing docs update, missing pins).
• [NIT] – minor polish.

Core Priorities

1. No hidden blast radius – prefer pinned refs, explicit versions, and documented breaking changes.
2. Read-only by default – never run terraform apply / terragrunt apply as part of this Skill.
3. Atomic diffs – split unrelated module/workflow changes into separate commits.
4. Repo rules first – AGENTS.md, CLAUDE.md, .tool-versions, and .pre-commit-config.yaml override defaults here.
5. Docs reflect reality – keep terraform-docs sections accurate when present.

Environment & Context Gathering

Start by gathering:

• Git context:
  • git status --porcelain
  • git diff --stat
  • git diff --cached --stat
  • git diff --cached --name-only
• Repo standards:
  • Read AGENTS.md / CLAUDE.md if present.
  • Detect .pre-commit-config.yaml, .tool-versions, Taskfile.yml.
• Tooling:
  • terraform version
  • terragrunt --version (if present)
  • tflint --version (if present)
  • terraform-docs --version (if present)

If pre-commit hooks fail due to tool-version mismatch, prefer installing the repo’s pinned tool versions (e.g. via asdf install or a repo task install:tools) over bypassing checks.

Checks Pipeline (Both Modes)

1. Scope changed files

   • Focus on changed .tf, .hcl, .json, .yml, and module README.md files.

2. Formatting

   • Terraform modules:
     • Run terraform fmt -recursive (or repo-preferred equivalent) on changed module directories.
   • Terragrunt repos:
     • Prefer running repo pre-commit hooks for formatting.
     • If formatting is manual, use the Terragrunt formatting command compatible with the pinned Terragrunt version.

3. Validate (focused, read-only)

   • Terraform modules:
     • For each changed module directory, run:
       • terraform init -backend=false
       • terraform validate
     • Clean up .terraform/ and lockfiles created during local validation.
     • Practical pattern (handles modules that reference an aws.global alias):
       • Create a temporary ci_providers.tf inside the module directory:
         • provider "aws" { region = "us-east-1" }
         • provider "aws" { alias = "global" region = "us-east-1" }
       • Then run init/validate, and delete ci_providers.tf afterwards.
     • Avoid committing .terraform/ directories. Only commit .terraform.lock.hcl if the repo explicitly wants lockfiles versioned.
   • Terragrunt repos:
     • Prefer focused validation/plans for only the changed stacks (avoid full run-all unless required).
     • If a pre-commit hook fails due to a Terragrunt CLI flag mismatch, treat it as a tool-version drift problem first:
       • Install the repo’s pinned Terragrunt version (e.g. via .tool-versions + asdf install).
       • Re-run pre-commit run.

4. TFLint (when configured)

   • If the repo uses tflint (pre-commit hook or .tflint.hcl), run it on changed modules/stacks.
   • If not configured, do not introduce a brand-new tflint setup as part of a formatting-only commit unless explicitly requested.
     • If tflint is desired but missing, propose a separate, atomic commit that adds a baseline .tflint.hcl + CI gate.

5. terraform-docs consistency (when used)

   • If a module README contains <!-- BEGIN_TF_DOCS -->, regenerate docs and ensure the resulting diff is committed.
   • Recommended command (adjust to repo conventions):
     • terraform-docs markdown table --output-file README.md --output-mode inject <module_dir>
   • If terraform-docs tries to generate provider lockfiles, prefer a repo-approved invocation (some repos use --lockfile=false).
   • After regeneration, check that git diff is clean (or explicitly commit the README changes as part of the same atomic change).
   • Treat “docs drift” as [SHOULD_FIX] (or [BLOCKING] when the repo enforces it in CI).

Atomic Commit Mode Additions

In atomic-commit mode, additionally:

• Refuse to approve the commit if the staged diff includes unrelated changes (split commits).
• Require all checks relevant to the touched files to pass (fmt/validate/lint/docs).
• Propose a commit message with no AI signature.

Output Format

Return:

• Verdict: READY or NOT READY
• Checks: list of commands run + pass/fail
• Changes made: brief list
• Remaining issues: with [BLOCKING] / [SHOULD_FIX] / [NIT]
• Proposed commit message: (atomic-commit mode only)