Content glow-up: content/docs/iac/get-started/terraform/next-steps.md

[pulumi-bot]

Important

Glow-up PR — human review required. Auto-merge is never armed on glow-up PRs and the automated PR-review sweep never approves them; it assigns the reviewers. Adjudicate the Backlog executed / Backlog declined tables below and merge manually.

Why this page

• Page: content/docs/iac/get-started/terraform/next-steps.md → /docs/iac/get-started/terraform/next-steps/
• Lane: glowup
• Strategic tier: 1 (no_retire: true)
• Traffic: 202 monthly visits (period 2026-02-17 to 2026-08-17; source CLICKSTREAM.FCT_PAGEVIEWS)
• Last reviewed: 2026-07-16 (attempts: 0)
• Selection score: 15.7294

This section is composed deterministically from the selection queue; do not edit it.

Backlog executed

Banked finding	Source PR	What changed
Vale nomenclature (L24): 'Pulumi deployments' → 'Pulumi Deployments' (deterministic). Prior review declined the capitalization because it would wrongly imply the hosted Deployments product.	#20318	Resolved the ambiguity instead of the casing: the bullet now reads "Deploy Terraform and Pulumi stacks together", matching the sibling orchestrate.md ("deploy both Terraform and Pulumi stacks together"). The Vale flag clears without asserting the product name.
Vale difficulty qualifier (L30): 'simple'.	#20318	"Begin with a simple coexistence pattern" → "Begin with one coexistence pattern".
Vale wordiness (L40): 'employ' is too wordy.	#20318	The sentence was rewritten as part of the new "Advanced integration patterns" lead-in; "employ" is gone.
Vale weasel word (L40): 'very' is a weasel word!	#20318	Same rewrite — "will be very dependent on your particular needs" → "depend on your particular needs".
Readthrough prerequisite-inversion (38-320, local_repair): "### Multi-stack architectures" — terraform.state state-referencing is used before it is defined or linked. The prior review could not repair it because the API in the samples was fabricated.	#20318	The fabricated API is gone from master (the samples now use the real terraform.state.getS3ReferenceOutput / .outputs[...], matching reference-state.md), so the local repair is now honest and was applied: a new orientation paragraph before the first sample names getS3ReferenceOutput, explains it is the S3 counterpart of the getLocalReference/getRemoteReference functions the reader already used, links back to Reference Terraform State, and says the result carries an outputs map. The first sample also gained its missing @pulumi/aws, @pulumi/pulumi, and @pulumi/terraform imports.
Readthrough buried-outcome (322-337, reconception): "## Learning resources" — the link sections a "Next Steps" reader actually wants sit below ~280 lines of advanced code.	#20318	Moved "Learning resources" (Documentation and guides, Community resources, Case studies) up to directly follow "What's next?", ahead of the advanced-pattern code. "Getting help and contributing to Pulumi" deliberately stays at the foot of the page, where it reads as the guide's closer alongside the feedback line.
Readthrough purpose-mismatch (16-24, reconception): lightweight recap-and-links page vs. advanced-patterns tutorial.	#20318	Resolved in favor of recap-and-links, matching the page's title and menu weight. With the link sections promoted, the page now reads recap → next steps → resources → optional deep dives, and a new lead-in explicitly frames the remainder as "optional reading: patterns to reach for once a basic coexistence setup is working… rather than as steps to follow in order." No advanced content was deleted — it is demoted to an appendix. clarity_flag is cleared.

Backlog declined

Ten banked findings were re-checked against current master and need no action. All were claim-lane items; the pre-step artifacts for this run report 0 contradicted/mismatch and 0 unverifiable across 23 verdicts, consistent with these having been resolved or shown to be false positives.

• c5 — .getOutput("...") on a Terraform state reference (contradicted). Already fixed on master. The samples use terraform.state.getS3ReferenceOutput(...) and read .outputs["..."]; the one surviving .getOutput() (L83) is on a pulumi.StackReference, where it is the correct API.
• c6 — terraform.state.S3Reference class (mismatch). Already fixed on master; no S3Reference constructor remains.
• c38 — Mercedes-Benz case study link (contradicted). Confirmed false positive, as the prior review found: the verdict was an artifact of a mismatched source_hint. Link retained (now site-relative).
• c29 / c30 — /docs/using-pulumi/adopting-pulumi/ (unverifiable). Already resolved on master; the page links the canonical /docs/iac/guides/migration/.
• c35 — pulumi/examples contains "hundreds" of real-world examples (unverifiable, volatile). Now verified rather than changed: gh api repos/pulumi/examples/contents/ returns 340 top-level entries, so "hundreds" is accurate. No edit.
• c42 — https://support.pulumi.com/ (unverifiable). Still HTTP 403 to automated fetches, which reads as bot protection rather than a dead link. Not a confident fix; left as-is.
• c46 — https://www.pulumi.com/events/ lists community events (unverifiable). Moot: the description on master already matches the live page.
• c47 — "Speak at meetups and conferences" framing overclaim. Already resolved on master; the entry now reads "Events & Workshops … Attend live workshops, technical demos, and community events".
• c48 — https://github.com/pulumi/docs/issues (unverifiable). The artifact's source_hint was unrelated (slack.pulumi.com). The link is this repository's own issue tracker and is correct; no edit.

Secondary sweep

• Style improvements: Cleared the three surviving Vale style nags (see Backlog executed). No other prose was rewritten.
• Structural fixes: Section order changed to recap → next steps → resources → advanced patterns → getting help, with a lead-in that labels the advanced half optional. This is the substance of the two banked reconception findings.
• Code formatting: Added the three missing imports to the first TypeScript sample so it stands alone. Existing samples already follow the hand-written constructor style; no reformatting.
• Terminology corrections: ## Getting help and Contributing to Pulumi → ## Getting help and contributing to Pulumi (H2+ sentence case, STYLE-GUIDE.md). "community slack" → "community Slack".
• Link improvements: Converted the nine absolute pulumi.com links (mixed https://pulumi.com/ and https://www.pulumi.com/) to site-relative paths — /community/, /blog/, /events/, /case-studies/…. Off-site links (github.com, youtube.com, slack.pulumi.com, support.pulumi.com) are unchanged. Deliberately did not add a /registry/packages/terraform/api-docs/state/gets3reference/ deep link in the new orientation paragraph: registry content is generated in pulumi/registry and not resolvable from this checkout, so the paragraph names the function in code font and links the in-guide page instead.
• Image and diagram improvements: No images on this page (flag-only pass; nothing to flag).
• Content enhancements: The two new paragraphs described above. No technical claim on the page was changed, added, or removed.

Screenshot check

No images. The page source references no screenshots, diagrams, or other content images (only the generic shared meta_image card, if any), so there is nothing to verify. (Determined from the source; the screenshot pass was skipped.)

Verification

• make lint: ✅ make lint re-verified by the workflow on 2f7fe89
• Glow-up scope self-check (verify-glowup-scope.py): pass — 1 changed path (the queued article), churn 80 of 400.
• Pre-step artifacts:
  • .verified-claims.json: 23 verdict(s); 0 contradicted/mismatch, 0 unverifiable
  • .vale-findings.json: 4 finding(s) — all four addressed
  • .readthrough-findings.json: ran=True, 0 finding(s)
  • .frontmatter-validation.json: 1 file(s); 0 alias collision(s)
• No pre-step reported an errors field. make lint initially failed on a missing js-yaml; yarn install resolved it and lint then reported 0 errors across 1846 files with Prettier clean.

[github-actions]

Pre-merge Review — Last updated 2026-08-21T14:58:45Z

Tip

Summary: This is a content polish pass on the final page of the "Pulumi for Terraform Users" get-started guide (content/docs/iac/get-started/terraform/next-steps.md), matching the shape of its siblings in that directory. It moves the "Learning resources" section up ahead of the advanced patterns, converts absolute https://www.pulumi.com/... links to site-relative paths, normalizes ordered lists to repeated 1. per the repo convention, adds the missing @pulumi/aws / @pulumi/pulumi / @pulumi/terraform imports to the first TypeScript sample, adds an orientation paragraph explaining that the remaining sections are optional and that the samples use terraform.state.getS3ReferenceOutput, and lowercases the "Getting help and contributing to Pulumi" heading. The wrongness that would block a reader here is a bad link target or a resource label that promises something the destination doesn't deliver — a reader following a "next steps" list has no other signal about where a link goes. Passes run: link-target resolution against the repo for every relative path introduced, external claim verification (16 claims), a cross-sibling read of all 9 pages in the guide directory, an import-vs-usage check on the changed code block, and a frontmatter sweep. All relative links introduced by this PR resolve to real pages; nothing found blocks merge.

Review confidence:

Dimension	Level	Notes
mechanics	HIGH
facts	MEDIUM	One claim about the size of the examples repository could not be confirmed from the fetched page.
cross-sibling consistency	HIGH

Investigation log

• Cross-sibling reads: 9 of 9 siblings
• External claim verification: 10 of 16 claims verified (1 unverifiable, 0 contradicted, 2 framing-drift) · 4 specialists (numerical, cross-reference, capability, framing); 0 cross-specialist corroborations · routed: 0 inline, 5 Pass 1, 2 Pass 2 (verified 1, contradicted 0, unverifiable 1), 9 Pass 3 (verified 6, contradicted 2, unverifiable 1).
• Cited-claim spot-checks: 2 of 2 cited claims fetched and compared
• Frontmatter sweep: ran on body + meta_desc
• Temporal-trigger sweep: ran (recency words present in diff; spot-check in-review)
• Code execution: not run (no static/programs/ change)
• Code-examples checks: not run (no fenced code blocks in content files)
• Editorial-balance pass: not run (not under content/blog/)

🚨 Outstanding	⚠️ Low-confidence	💡 Pre-existing	✅ Resolved
0	3	1	0

🔍 Verification trail

17 claims extracted · 10 verified · 1 unverifiable · 0 contradicted · 2 framing-drift

• L24 in content/docs/iac/get-started/terraform/next-steps.md "Pulumi allows users to deploy Terraform and Pulumi stacks together." → ➖ not-a-claim (evidence: This bullet is a recap of skills taught earlier in the same guide (referencing Terraform state via terraform.state.getS3ReferenceOutput, using pulumi.StackReference to combine Terraform- and Pulumi-managed stacks) — it summarizes the…; source: repo:content/docs/iac/get-started/terraform/next-steps.md)
• L34 in content/docs/iac/get-started/terraform/next-steps.md "1. Consider migration: When ready, plan a gradual migration to Pulumi for new projects" → ➖ not-a-claim (evidence: This line is a piece of editorial/advisory guidance ("Consider migration: When ready, plan a gradual migration...") in a numbered list of suggested next steps authored by Pulumi for its own docs guide. It is not a falsifiable factual…; source: repo:content/docs/iac/get-started/terraform/next-steps.md)
• L42-46 in content/docs/iac/get-started/terraform/next-steps.md "The 'Pulumi vs Terraform' comparison page is located at /docs/iac/comparisons/terraform/ and provides a detailed comparison of features." → ✅ verified (evidence: The page content/docs/iac/comparisons/terraform/_index.md exists at the path /docs/iac/comparisons/terraform/, titled "Pulumi vs. Terraform", with the text "This page covers what each tool is, a feature-by-feature comparison..." and a…; source: repo:content/docs/iac/comparisons/terraform/_index.md)
• L46 in content/docs/iac/get-started/terraform/next-steps.md "* Policy as Code: Infrastructure governance and compliance" → ✅ verified (evidence: The page at /docs/insights/policy/ exists with title "Policies" and describes "Pulumi Policies enables you to implement policy as code across your entire cloud infrastructure" with compliance/governance content (CIS, HITRUST, NIST, PCI…; source: repo:content/docs/insights/policy/_index.md)
• L50 in content/docs/iac/get-started/terraform/next-steps.md "The Pulumi Community page is located at /community/ and includes a community Slack and forum." → ✅ verified (framing: Source says "Slack and GitHub Discussions"; claim generalizes "GitHub Discussions" as "forum," which is an accurate characterization of that feature.; evidence: The Pulumi Community page at pulumi.com/community/ states: "Find us on Slack and GitHub Discussions, and join our monthly community meetup for the Pulumiverse," confirming it links to a community Slack and a discussion forum (GitHub…; source: https://www.pulumi.com/community/)
• L51 in content/docs/iac/get-started/terraform/next-steps.md "The Examples Repository at https://github.com/pulumi/examples contains hundreds of real-world examples." → 🤷 unverifiable (evidence: The pre-fetched page body is truncated to just the repo title/description ("Infrastructure, containers, and serverless apps to AWS, Azure, GCP, and Kubernetes... all deployed with Pulumi") and does not show a count of examples or file…; source: https://github.com/pulumi/examples; intuition: The repo does plausibly contain hundreds of example subdirectories across languages/clouds, but the fetched snippet…)
• L52-53 in content/docs/iac/get-started/terraform/next-steps.md "The Pulumi YouTube Channel is located at https://www.youtube.com/pulumitv and contains video tutorials and demos." → ✅ verified (evidence: The URL https://www.youtube.com/pulumitv returns HTTP 200 and resolves to a live YouTube channel page (Pulumi's official channel), consistent with the claim that this is the Pulumi YouTube Channel containing video content.; source: https://www.youtube.com/pulumitv)
• L53 in content/docs/iac/get-started/terraform/next-steps.md "* Pulumi YouTube Channel: Video tutorials and demos" → ✅ verified (evidence: The URL https://www.youtube.com/pulumitv resolves to Pulumi's official YouTube channel "PulumiTV," described as "Infrastructure as Code in any programming language," matching the claim's description of it as Pulumi's YouTube channel for…; source: https://www.youtube.com/pulumitv)
• L57-59 in content/docs/iac/get-started/terraform/next-steps.md "There is a case study titled 'Mercedes-Benz's Platform Engineering' located at /case-studies/mercedes-benz/ describing large-scale infrastructure modernization." → 🌀 framing-drift (framing: shifted — source page is titled "Mercedes-Benz R&D" case study about unifying app/infra teams; claim invents title "Mercedes-Benz's Platform Engineering"; evidence: The case study at /case-studies/mercedes-benz/ exists and describes MBRDNA's use of Pulumi, but its actual title is "Mercedes-Benz R&D" (page title: "Mercedes-Benz R&D | Case Studies | Pulumi"), not "Mercedes-Benz's Platform Engineering"…; source: https://www.pulumi.com/case-studies/mercedes-benz/)
• L58 in content/docs/iac/get-started/terraform/next-steps.md "* Mercedes-Benz's Platform Engineering: Large-scale infrastructure modernization" → ✅ verified (evidence: The page at /case-studies/mercedes-benz/ exists and states: "Case Study · Mercedes-Benz Research and Development used Pulumi to bring their application and infrastructure teams closer together," describing MBRDNA's platform enabling…; source: https://www.pulumi.com/case-studies/mercedes-benz/)
• L59 in content/docs/iac/get-started/terraform/next-steps.md "* Lemonade's Insurance Platform: Rapid development with Pulumi and Terraform" → ✅ verified (framing: Source describes Lemonade moving from Terraform to Pulumi to move faster; claim's short description "Rapid development with Pulumi and Terraform" is a…; evidence: The case study page at /case-studies/lemonade/ confirms Lemonade's story: "Starting with legacy Hashicorp Terraform for configuring their infrastructure on AWS, Lemonade wanted to take advantage of Pulumi's building-blocks approach... to…; source: https://www.pulumi.com/case-studies/lemonade/)
• L65 in content/docs/iac/get-started/terraform/next-steps.md "The terraform.state.getS3ReferenceOutput function is the S3 counterpart of the getLocalReference and getRemoteReference functions in the…" → ✅ verified (evidence: pulumi/pulumi-terraform source confirms all three functions live in the same package's state module: sdk/nodejs/state/getS3Reference.ts exports getS3Reference/getS3ReferenceOutput invoking terraform:state:getS3Reference…; source: gh search code --owner pulumi "GetS3Reference" (pulumi/pulumi-terraform sdk/nodejs/state/getS3Reference.ts, getLocalReference.ts))
• L132 in content/docs/iac/get-started/terraform/next-steps.md "1. State migration: Transfer state ownership gradually, resource-by-resource" → ➖ not-a-claim (evidence: This is a step in Pulumi's own recommended migration guidance for transitioning from Terraform to Pulumi, describing the author's own suggested approach rather than a falsifiable third-party assertion.; source: content/docs/iac/get-started/terraform/next-steps.md)
• L18-24 in content/docs/iac/get-started/terraform/next-steps.md "The 'you learned how to' recap lists every step of the Pulumi for Terraform Users guide." → ⚔️ mismatch (evidence: the guide directory contains 11 steps, including terraform-state-backend.md ("Store Terraform State in Pulumi Cloud", weight 9) and terraform-remote-execution.md ("Remote Execution", weight 10), neither of which appears in this page's five-bullet recap of what the reader learned; source: repo:content/docs/iac/get-started/terraform/)
• L370 in content/docs/iac/get-started/terraform/next-steps.md "The Pulumi Blog is located at /blog/." → ✅ verified (evidence: Search results confirm the Pulumi Blog resides at pulumi.com/blog/, e.g. pages like "https://www.pulumi.com/blog/pulumi-insights/" and "https://www.pulumi.com/blog/series/" are all served under the /blog/ path.; source: https://www.pulumi.com/blog/series/)
• L371 in content/docs/iac/get-started/terraform/next-steps.md "The 'Events & Workshops' page is located at /events/ and covers live workshops, technical demos, and community events." → ✅ verified (evidence: The page at https://www.pulumi.com/events/ is titled "Pulumi Events & Workshops" and lists live workshops (e.g. "Connect existing Terraform workloads to Pulumi Cloud... — live workshop"), technical demos, and community/industry events…; source: https://www.pulumi.com/events/)
• L372 in content/docs/iac/get-started/terraform/next-steps.md "The 'User Groups' page is located at /community/ and allows users to join or start a local user group." → 🌀 framing-drift (framing: overclaim — claim asserts the /community/ page is specifically the "User Groups" page for joining/starting local groups, but the fetched page content covers…; evidence: The pulumi.com/community/ page does exist, but its actual content is about Slack, GitHub Discussions, a monthly community meetup, contributing providers on GitHub, and a support portal — it says "Want to talk to other Pulumi users and…; source: https://www.pulumi.com/community/)

🚨 Outstanding in this PR

No outstanding findings in this PR.

⚠️ Low-confidence

Review each and resolve as appropriate — these don't block the PR.

• [L51] content/docs/iac/get-started/terraform/next-steps.md — "The Examples Repository at https://github.com/pulumi/examples contains hundreds of real-world examples." — verdict: unverifiable. The repository landing page doesn't state an example count, so "hundreds" couldn't be confirmed either way. This is pre-existing wording that the PR relocated rather than authored, and the link target itself is live, so it doesn't block merge. Author question: do you want to keep the "hundreds" quantifier, or soften it to something that can't drift — e.g. **[Examples Repository](https://github.com/pulumi/examples)**: Browse real-world examples across every supported language and cloud?

• [L57-59] content/docs/iac/get-started/terraform/next-steps.md — "There is a case study titled 'Mercedes-Benz's Platform Engineering' located at /case-studies/mercedes-benz/ describing large-scale infrastructure modernization." — verdict: framing-drift; framing: shifted — source page is titled "Mercedes-Benz R&D" case study about unifying app/infra teams; claim invents title "Mercedes-Benz's Platform Engineering". The link resolves (content/case-studies/mercedes-benz.md exists), so this isn't broken — but the label doesn't match the case study, which is titled "Mercedes-Benz: Programming the Cloud" and is about bringing Mercedes-Benz R&D's application and infrastructure teams closer together, not about large-scale infrastructure modernization. The same drift affects the two sibling bullets in that list: /case-studies/snowflake/ is "Snowflake: Testable, Repeatable Infrastructure" (not a multi-cloud strategy story), and the Lemonade study is about moving off Terraform onto Pulumi rather than "rapid development with Pulumi and Terraform". Since the PR is already rewriting these three lines, consider aligning all three with their destinations:

  * **[Snowflake: Testable, Repeatable Infrastructure](/case-studies/snowflake/)**: Treating infrastructure as software, with tests
  * **[Mercedes-Benz: Programming the Cloud](/case-studies/mercedes-benz/)**: Bringing application and infrastructure teams closer together
  * **[Lemonade](/case-studies/lemonade/)**: Moving from Terraform to Pulumi to ship faster
  

• [L372] content/docs/iac/get-started/terraform/next-steps.md — "The 'User Groups' page is located at /community/ and allows users to join or start a local user group." — verdict: framing-drift; framing: overclaim — claim asserts the /community/ page is specifically the "User Groups" page for joining/starting local groups, but the fetched page content covers Slack, GitHub Discussions, a monthly community meetup, provider contribution, and the support portal. There is no local-user-group program on that page, so a reader who clicks "User Groups" expecting to find or start one lands somewhere that can't help them. The link itself is fine; the label is the problem. Note this also duplicates the /community/ link already in the "Community resources" list above (L50). Suggested rewrite:

  * **[Community meetup](/community/)**: Join the monthly Pulumiverse community meetup
  

💡 Pre-existing issues in touched files (optional)

• [L18-24] content/docs/iac/get-started/terraform/next-steps.md — the "You've completed the Pulumi for Terraform Users guide and learned how to:" recap lists five skills, but the guide has since grown two more steps that the recap never picked up: Store Terraform State in Pulumi Cloud (terraform-state-backend.md, weight 9) and Remote Execution (terraform-remote-execution.md, weight 10). A reader finishing all 11 steps sees a summary that omits the last two things they did. Pre-existing: only the fifth bullet ("Deploy Terraform and Pulumi stacks together") is touched by this PR; the gap predates it. Worth two extra bullets while the section is open, but not a blocker.

✅ Resolved since last review

No items resolved since the last review.

📜 Review history

• 2026-08-21T14:58:45Z — No blockers: every relative link introduced resolves and the added imports match the sample's usage; flagged three resource labels that don't match what their destinations actually contain, plus a guide recap that omits the two newest steps (2f7fe89)

---

• Refresh this review — comment @claude #update-review. Say what you fixed, or which finding you dispute and why; both work in the same mention.
• Ask for anything else — comment @claude with no hashtag (questions, one-off fixes). Leaves this review untouched.

Important

Please don't hide, resolve, or delete this comment! It breaks things!

📖 How pre-merge review works — the full lifecycle, short-circuits, and escape hatches.

[pulumi-bot]

Your site preview for commit 2f7fe89 is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-21046-2f7fe890.s3-website.us-west-2.amazonaws.com

Changed pages:

• /docs/iac/get-started/terraform/next-steps/

[jkodroff]

Need to make sure that outputs are linked as a concept or otherwise explained in this doc and that we're not just mentioning this concept out of the blue.

[jkodroff]

Minor nit, otherwise LGTM.