Rewrite Merge Queue overview for skeptical CI engineers

[samgutentag]

Summary

Ground-up rewrite of merge-queue/merge-queue.mdx, triggered by Eli's feedback on 2026-05-21:

• "Big three items don't make sense or are outright lies"
• "Calls out Nx/Bazel but not other build systems"
• "Not selling — no clear audience, layout sucks"

What changed

• Hook replaced. Marketing-style intro ("enterprise upgrade", "fire and forget", "cut CI costs up to 90%") swapped for a two-paragraph mechanic-first intro that defines a merge queue, names predictive testing as the universal baseline, and identifies the three mechanics Trunk layers on top.
• Three stacked sections → 3-column Tiles for batching / parallel queues / anti-flake protection. Each tile is a one-line description + icon + link to the deep page where the Vidyard / iframely visuals already live.
• New "When does this make sense?" decision tree maps symptoms (CI bill climbing, monorepo with non-overlapping lanes, flaky tests, GHMQ choking) to mechanics in recognition voice.
• "More to dial in" section adds Direct merge to main (the only architectural optimization in the settings UI that wasn't already represented at the top), Priority merging, Predictive testing internals, and Testing concurrency.
• Stripped factually wrong claims that were on the old page: "Automatic quarantine of flaky tests" (wrong product — that's Flaky Tests), "Batch up to 100 PRs" (no such limit; default is 4, recommended max is small), "cut CI costs up to 90%" (the batching sub-page documents 50–70%).
• "Native Bazel/Nx integration" → "Bazel, Nx, or any build system via the impacted-targets API" — the parallel-queues sub-page already documents the "Other" path; the old overview was excluding a real customer segment.

Audience targeting

This rewrite uses the skeptical-engineer overview pattern (committed locally; not yet shared). The marketing site does the selling; /getting-started/ does onboarding; this page does the "is this worth ten more minutes?" mental model. No customer names, no numeric outcome claims — mechanics + visuals are the only evidence.

Items flagged for review

• Tile descriptions are tight on purpose. Mintlify Tiles truncate after a short visible line — descriptions are deliberately 20–25 chars. Open to making them even shorter or dropping description entirely.
• Icons are boxes-stacked, columns-3, shield-check (FontAwesome / Lucide resolved by Mintlify). Easy to swap.
• Direct merge to main is included in "More to dial in" based on the settings UI inventory. Not sure if it deserves a tile of its own — currently feels more like a niche optimization than a peer to the big three.
• Tile fallback question — Tile component is new to docs2 (no other page uses it yet). Card is more common; if Tile renders weirdly on prod, swap is mechanical.

Test plan

• Review on Mintlify preview when it builds
• Check tile layout on narrow viewports (sidebar makes the available width tight)
• Verify all linked sub-pages still exist (predictive-testing, priority-merging, direct-merge-to-main, etc.)
• Eli does a sanity read against the original three complaints

🤖 Generated with Claude Code