4 Skills, expectations, and escalation
Reviewing infrastructure code is a skill that develops with practice. This chapter explains what is expected of reviewers at different levels of experience, how to calibrate your confidence, and when to ask for help.
4.1 What reviewers are expected to do
A reviewer’s job is not to be a human linter. Automated tools handle formatting and many common errors. Your job is to apply judgement where tools cannot:
- Is this the right approach for this problem?
- Does this change do what the author says it does?
- Could this change cause unintended harm, now or later?
- Is the code clear enough that someone else could maintain it?
You do not need to know every Terraform resource type or every cloud provider feature. You do need to read carefully, ask questions when something is unclear, and be willing to say “I am not sure — let’s check.”
4.2 Expectations by experience level
Reviewing as someone new to infrastructure
If you are new to Terraform or cloud infrastructure, you can still add value as a reviewer. Focus on:
- Clarity and intent: Is it clear what the code is doing? Would you be able to explain it to someone else? If not, that is a signal to ask for better comments or documentation.
- The sensitivity checklist: Are there any hardcoded values that look like secrets? Does the PR description match what the code actually does?
- Automated tool output: Has the author run the required tools (
terraform validate,checkov,tflint)? Are there any unresolved findings?
It is fine to approve a PR while noting that you have reviewed it from a content clarity perspective and suggest another reviewer checks the technical implementation. Saying what your review covers is more honest and useful than silence.
Reviewing as someone with some infrastructure experience
If you have written Terraform before but are not a platform specialist, you should additionally check:
- Resource configuration: Are the settings appropriate? Are required fields set? Are optional fields that have security implications (logging, encryption, public access) addressed?
- IAM and access: Does the code follow least-privilege principles? Are roles specific and scoped correctly?
- Environment targeting: Does the change go to the right environment directory? Does it affect only what it should?
- The plan: If a plan output is attached, does it show the expected changes? Are there any unexpected replacements?
Reviewing as an experienced platform engineer
If you have deep infrastructure experience, you should additionally check:
- State implications: Could this change cause Terraform to lose track of existing resources? Are there resources being renamed or moved that require
terraform state mv? - Module design: If the change touches a shared module in
modules/, what is the impact on all environments that use it? - Provider and version constraints: Are the pinned versions appropriate? Are there known issues with the specified versions?
- Security posture: Does the infrastructure posture align with the environment’s classification requirements?
4.3 Calibrating your confidence
You do not need to be certain about everything you review. A useful rule of thumb:
- Confident: You understand what the code does and why. You can approve or request changes with clear reasoning.
- Uncertain: Something looks odd or unfamiliar. Ask a question in the review rather than guessing. “Can you explain why X is configured this way?” is a legitimate and valuable review comment.
- Out of your depth: The change touches something you do not understand well enough to assess. This is a signal to escalate.
Approving a PR you do not understand is more dangerous in infrastructure than in application code, because the consequences can be immediate and hard to reverse. When in doubt, ask.
4.4 When to escalate
Escalate to a more experienced platform engineer when:
- The change affects production or pre-production environments and you are not confident you understand all the implications
- The change modifies shared modules used by multiple environments
- The change touches IAM, network perimeter rules, or security controls
- The plan shows resource replacements (
-/+) that are not clearly explained and expected - The automated tools report findings that the author has dismissed without a clear explanation
- You have identified a potential secret or sensitive value in the code
Escalation is not a failure. It is the correct response to uncertainty in a context where mistakes have real consequences.