policy analyze blog post

[Frassle]

Blog post to announce the new policy analyze command added to the CLI (pulumi/pulumi#22250)

[claude]

Docs Review — pulumi policy analyze blog post

Issues

1. Missing meta_image (frontmatter) — meta_image is required for blog posts and is not set. Without it, social shares will use a default placeholder image. Add a meta_image field pointing to a generated or selected image. You can use /blog-meta-image to generate one.

2. Missing bluesky key in social: block (line 14–15) — The social: block has twitter and linkedin but is missing bluesky. These auto-post on merge. Add a bluesky entry (max 300 characters), e.g.:

   social:
       twitter: "..."
       linkedin: "..."
       bluesky: "New in Pulumi CLI: pulumi policy analyze runs policy packs against existing stack state — fast policy testing without running your program or making provider calls."
   

3. Missing documentation — No corresponding docs exist in content/docs/ for pulumi policy analyze. Since this post announces a new CLI command, there should be documentation covering usage, flags, and examples (e.g., under content/docs/iac/cli/commands/ or content/docs/iac/packages-and-automation/crossguard/).

4. First-mention links missing — Per blog review criteria, the first mention of every tool, technology, or product should be hyperlinked:

   • Line 20: "Pulumi CLI" — link to /docs/iac/cli/
   • Line 22: "policy packs" — link to /docs/iac/packages-and-automation/crossguard/
   • Line 30: pulumi preview and pulumi up — link to their respective CLI docs

5. "We just merged" phrasing (line 20) — This will age poorly. Consider more evergreen phrasing like "Pulumi CLI now includes" or "We've added a new Pulumi CLI command."

6. Title contains backticks (line 2) — The title "Introducing `pulumi policy analyze` for existing stacks" renders backticks literally in meta tags and social cards. Consider removing backticks from the title or rephrasing.

Minor suggestions

• Line 26, "Why this command matters" — Consider answer-first phrasing for the H2 per SEO guidelines, e.g., "Faster policy iteration without full deployments."
• Line 71, "In short, this command helps both humans and agents…" — This reads as a summary/TL;DR sentence. Consider cutting it since the preceding list already makes this point.
• The post has no CTA shortcode. Consider adding a {{< blog/cta-button >}} at the end linking to CrossGuard docs or the CLI install page.

What looks good

• <!--more--> break is well-positioned after the intro.
• Social post lengths are within limits (Twitter: 160 chars, LinkedIn: 267 chars).
• Author profile and avatar exist.
• Sentence case on H2+ headings.
• Clean structure, good use of ordered lists.
• No spelling/grammar issues found.
• No AI writing pattern flags (no em-dash overuse, no hedging, varied sentence structure).

Publishing readiness checklist

• <!--more--> break present after intro
• meta_image set and not the default placeholder — MISSING
• meta_image uses current Pulumi logos — N/A (no meta_image)
• Author profile exists with avatar
• All links resolve
• Code examples correct with language specifiers
• No animated GIFs used as meta_image
• Images have alt text; screenshots have 1px gray borders — N/A (no images)
• Title ≤60 chars or allow_long_title: true set
• social: block present with copy for twitter, linkedin, bluesky — Missing bluesky

---

Mention me (@claude) if you'd like additional reviews or help generating the meta image.

[pulumi-bot]

Your site preview for commit 9a68fb6 is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-18261-9a68fb6e.s3-website.us-west-2.amazonaws.com.

still need meta images

[pulumi-bot]

Your site preview for commit d572779 is ready! 🎉

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

[pulumi-bot]

Your site preview for commit aedc70a is ready! 🎉

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

[pulumi-bot]

Your site preview for commit f1a9bb0 is ready! 🎉

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

---

Lighthouse Performance Report

Commit: f1a9bb09 | Metric definitions

Page	Device	Score	FCP	LCP	TBT	CLS	SI
Homepage	Mobile	🟡 87	2.3s	2.3s	201ms	0.014	6.3s
Homepage	Desktop	🟡 81	0.6s	1.0s	0ms	0.235	2.5s
Install Pulumi	Mobile	🔴 44	4.4s	5.9s	58ms	0.431	7.0s
Install Pulumi	Desktop	🟢 94	1.0s	1.4s	0ms	0.020	1.0s
AWS Get Started	Mobile	🟡 67	4.2s	5.6s	61ms	0.093	4.2s
AWS Get Started	Desktop	🟡 89	1.0s	1.4s	0ms	0.033	2.5s

[Frassle]

@claude can you re-review this

[claude]

Claude finished @Frassle's task in 1m 33s —— View job

---

Re-review — pulumi policy analyze blog post

• Read current blog post content
• Compare against previous review issues
• Post updated review

---

What's been fixed since the last review

• ✅ meta_image: meta.png and feature_image: feature.png — both added (images present in PR)
• ✅ bluesky social entry — added (161 chars, within 300-char limit)
• ✅ "We just merged" phrasing — replaced with "You can now run…"
• ✅ Release version info added — "available in Pulumi v3.229.0" with link
• ✅ Summary sentence ("In short, this command helps both humans and agents…") — removed
• ✅ kramhuber's wording suggestions applied

Great progress. The post is in much better shape.

---

Remaining issues

1. Missing CLI command documentation (from previous review, still unresolved)

No pulumi_policy_analyze.md exists under content/docs/iac/cli/commands/. The other pulumi policy subcommands all have corresponding docs pages there (e.g., pulumi_policy_publish.md, pulumi_policy_enable.md). This should be added before or alongside the blog post going live.

Fix this →

2. First-mention links still missing

• Line 21: "policy packs" — should link to /docs/insights/policy/policy-packs/
• Line 34: `pulumi preview` and `pulumi up` — should link to /docs/iac/cli/commands/pulumi_preview/ and /docs/iac/cli/commands/pulumi_up/

Fix this →

3. Title still contains backticks

title: "Introducing \pulumi policy analyze` for existing stacks"— backticks render literally in HTML<title>tags and OG meta tags. Consider:title: "Introducing pulumi policy analyze for existing stacks"` or wrap the command name differently.

4. No CTA at end of post

The post ends abruptly. A {{< blog/cta-button >}} pointing to the policy docs or CrossGuard install page would close the loop for readers.

---

Publishing readiness checklist

• `` break present after intro
• meta_image set (meta.png)
• feature_image set (feature.png)
• Author profile exists with avatar
• Code examples have language specifiers
• No animated GIFs
• Bluesky/Twitter/LinkedIn social copy present, within character limits
• Evergreen phrasing (version number cited)
• First-mention links on key terms — MISSING
• CLI command docs page exists for pulumi policy analyze — MISSING
• Title backticks removed — STILL PRESENT
• CTA shortcode at end of post — MISSING

The post is approvable as-is from a content quality standpoint, but the missing CLI docs page (#1) is the most important outstanding item.

[Frassle]

The release with this command has gone out now.

[claude]

Docs Review — pulumi policy analyze blog post

Overall this is a well-structured, clearly written blog post. A few items to address:

Issues

1. Title casing (line 2): The H1 title "Introducing pulumi policy analyze for existing stacks" should use Title Case per the style guide. Suggested fix:

   title: "Introducing Pulumi Policy Analyze for Existing Stacks"
   

   Since pulumi policy analyze is a CLI command, an alternative acceptable form would be: "Introducing the pulumi policy analyze Command for Existing Stacks" — but either way, the non-command words need Title Case.

2. Missing CLI reference documentation: There is no pulumi policy analyze CLI reference page in content/docs/iac/cli/commands/. The blog post announces the command but the docs site has no corresponding reference page. This should be tracked and added (possibly auto-generated from the CLI, like other command pages).

3. Publish date is in the past (line 3): The date is set to 2026-03-28, which is before today (2026-04-02). Verify this is intentional — if the post hasn't been published yet, the date may need updating.

Minor suggestions

4. Line 79 — long paragraph: The paragraph starting with "For example, an agent tasked with fixing a policy violation..." is 4+ sentences and quite dense. Consider breaking it into a shorter paragraph or a numbered list for scannability.

5. Line 65 — first mention of "AI" not linked: The "AI and agent workflows" section could benefit from linking to Pulumi's AI/automation docs (e.g., /docs/insights/copilot/) on first mention, per the review criteria that first mentions of products/tools should be hyperlinked.

What looks good

• social: block has all three keys (twitter, linkedin, bluesky) ✓
• meta_image is set to meta.png ✓
• <!--more--> break is present after intro ✓
• Author profile (fraser-waters) exists with avatar ✓
• All internal links resolve (/docs/insights/policy/policy-packs/, /docs/iac/cli/commands/pulumi_preview/, /docs/iac/cli/commands/pulumi_up/, /docs/insights/policy/) ✓
• Code examples have language specifiers (bash) ✓
• CTA is specific and uses {{< blog/cta-button >}} shortcode ✓
• Meta description is 144 chars (under 160) ✓
• Title is 53 chars (under 60) ✓
• No "easy"/"simple" language ✓
• H2 headings use sentence case ✓

Publishing readiness checklist

• social: block has all three keys: twitter, linkedin, bluesky
• meta_image set and not the default placeholder
• meta_image uses current Pulumi logos — unable to verify image content in CI; please confirm manually
• <!--more--> break present after intro
• Author profile exists with avatar
• All internal links resolve
• Code examples correct with language specifiers
• No animated GIFs used as meta_image
• Images have alt text; screenshots have 1px gray borders — no images are referenced in the Markdown body (only frontmatter), so N/A
• Title ≤60 chars or allow_long_title: true set

---

Mention me (@claude) if you'd like additional reviews or fixes.