kaiohenricunha Terragrunt Specialist
Structured investigation for Terragrunt-managed Terraform codebases. Five phases: gather context, diagnose, design, recommend, verify.
Arguments
$0— repo root, specificterragrunt.hclpath, or problem description. Required.
Phase 1: Context Gathering
- Map the full hierarchy:
find . -name "terragrunt.hcl" | sort - Identify the root
terragrunt.hcl(containsremote_state,terraform_version_constraint). - Check include chain:
grep -r "include" . --include="terragrunt.hcl" -l grep -r "find_in_parent_folders" . --include="terragrunt.hcl" -l - List all dependency blocks:
grep -r "dependency" . --include="terragrunt.hcl" -A5
Phase 2: Diagnosis
DRY pattern health:
# Check for duplicated locals or inputs across leaves
grep -r "locals" . --include="terragrunt.hcl" -l
grep -r "inputs\s*=" . --include="terragrunt.hcl" -l
Remote state config:
grep -r "remote_state" . --include="terragrunt.hcl" -A10
run-all safety:
terragrunt run-all plan --terragrunt-non-interactive 2>&1 | head -100
Hook correctness:
grep -r "before_hook\|after_hook\|error_hook" . --include="terragrunt.hcl" -A8
Phase 3: Design / Root-Cause Analysis
Map symptoms to causes:
| Symptom | Common Causes | Check |
|---|---|---|
run-all applies wrong order |
Missing dependency block |
Dependency graph via run-all plan |
mock_outputs plan fails |
Wrong type in mock (string vs list) | Compare mock type to real output type |
| DRY violation | Same inputs block in multiple leaves |
Extract to parent locals + read_terragrunt_config |
| State collision | Two leaves share the same backend key | Grep remote_state.config.key across leaves |
| Hook runs unexpectedly | Hook trigger is run_if on wrong command |
Check commands list in hook block |
Cite file:line for every finding.
Phase 4: Recommendations
Output findings in priority order:
[CRITICAL] <title>
File: <file:line>
Issue: <one sentence>
Evidence: <config snippet>
Fix: <specific change, with HCL diff>
Trade-off: <alternative and its downside, if meaningful>
Order: CRITICAL → WARNING → INFO.
Phase 5: Verification
After fixes are applied:
terragrunt validateon affected leaves.terragrunt run-all plan --terragrunt-non-interactive— confirm correct dependency order.- Verify no two leaves share the same remote state key.
- If
mock_outputschanged, confirmplan --terragrunt-non-interactivesucceeds on dependent modules. - Run hooks manually to confirm they execute in the expected phase.
Reference Docs
| File | When to use |
|---|---|
dry-patterns.md |
include, read_terragrunt_config, locals reuse |
run-all.md |
run-all orchestration, dependency graph, scoping |
env-hierarchy.md |
Account → region → env → module layout patterns |
hooks.md |
before_hook, after_hook, error_hook design |
dependency-blocks.md |
Explicit deps, mock_outputs, cross-stack references |