Rewrite Merge Queue overview for skeptical CI engineers by samgutentag · Pull Request #63 · trunk-io/docs2

samgutentag · 2026-05-21T23:10:12Z

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

samgutentag · 2026-05-26T18:37:21Z

Verification status (2026-05-29): live

Verified: customers can use this. Ready to publish.

Flag state: no feature flag involved; LaunchDarkly not consulted (nothing to read)
Eng PR: none (content rewrite)
Flag: none
Signals: No engineering dependency and no feature flag. This is a ground-up rewrite of the Merge Queue overview page, replacing marketing-style claims with mechanic-first descriptions of existing shipped features (batching, parallel queues, anti-flake protection, predictive testing, direct merge to main, priority merging). All referenced features are already live and documented on sub-pages. Triggered by Eli feedback on 2026-05-21.

Ready to publish after editorial review.

Generated by Claude Code

samgutentag · 2026-05-31T14:17:57Z

Verification status (May 31, 2026): live

Editorial rewrite of existing Merge Queue overview — no feature flag, no eng dependency.

Flag state: not consulted
Eng PR: none
Flag: none
Signals: documents existing, shipped behavior; no gating required

Next action: merge this PR.

Generated by Claude Code

samgutentag · 2026-06-01T14:21:16Z

Verification status (2026-06-01): live

Verified: customers can use this. Ready to publish.

Flag state: LaunchDarkly not consulted (editorial rewrite, no flag, no eng dependency).
Eng PR: none referenced.
Flag: none.
Signals: this is a ground-up rewrite of the existing Merge Queue overview page. It documents already-shipped mechanics (batching, parallel queues, anti-flake protection) and strips factually wrong claims from the old page. No new feature to gate.

Unchanged from prior sweep: still live. PR is currently CONFLICTING (needs rebase); does not affect this verdict. The page makes specific factual corrections (default batch size 4, removal of the bogus "100 PR" limit and "90% cost" claim) that read as accurate against the batching sub-page, but those are editorial corrections rather than rollout-gated claims.

Generated by Claude Code

samgutentag · 2026-06-02T14:16:41Z

Verification status: live - June 2, 2026

Verified: customers can use this. Ready to publish.

Flag state: Not applicable; this is a content rewrite of an existing production page (Merge Queue overview)
Eng PR links: None needed; Merge Queue is an existing production feature
Flag: none
Signals checked: PR body; Merge Queue has been live for years
Suggested next action: Ready for content review and merge.

Generated by Claude Code

samgutentag · 2026-06-03T14:22:00Z

Verification status (June 3, 2026): live

Editorial rewrite of the Merge Queue overview documenting existing, fully-shipped features. All referenced behavior is live in production. No new feature gates.

Flag state: N/A — no LaunchDarkly flag; documents existing behavior only
Eng PR links: none (editorial rewrite, no new engineering changes)
Flag: none
Signals checked: prior sweep verify chain (consistent live since May 26), content review — all referenced features confirmed shipped
Suggested next action: ready to merge

Generated by Claude Code

samgutentag · 2026-06-04T14:21:02Z

Verification status (June 4, 2026): live

Content rewrite PR; no feature flag or pending eng dependency identified. Feature is available in production.

Flag state: N/A — no LaunchDarkly flag identified
Eng PR: none required; content documents existing behavior
Flag: none
Signals checked: PR body, prior sweep chain
Suggested next action: ready to merge

Generated by Claude Code

samgutentag · 2026-06-05T14:20:02Z

Docs PR Verify — 2026-06-05 | Verdict: live ✅

Eng PR(s): n/a (content rewrite of existing live features) | Flag: none | LD: n/a

Documents already-live features. No new engineering change required. Ready to merge.

Auto-generated by Daily Docs PR Verify Sweep · 2026-06-05

Generated by Claude Code

samgutentag · 2026-06-08T14:14:25Z

Docs PR Verdict — 2026-06-08


Verdict	🟢 live
Eng refs	—
LD flag	—
Notes	Merge Queue overview rewrite — pure doc change, no feature gate.

Next sweep: 2026-06-09

Generated by Claude Code

samgutentag · 2026-06-09T14:17:23Z

✅ Verdict: live — June 9, 2026

Feature confirmed live in production across all signals (prior sweep chain verified, no regression signals today).

Verified by Daily Docs Sweep · June 9, 2026

Generated by Claude Code

samgutentag · 2026-06-10T14:23:17Z

❓ Verdict: unknown — June 10, 2026

⚠️ Verdict changed: live → unknown

Signal	Detail
Eng PR	none referenced
LD flag	none
Linear	none

Could not determine rollout state from available signals. No eng PR, no LD flag, no Linear ticket to verify against. PR documents existing Merge Queue behavior — editorial review required before merging.

Verified by Daily Docs Sweep · June 10, 2026

Generated by Claude Code

samgutentag · 2026-06-11T14:27:00Z

✅ Verdict: live — June 11, 2026

Content rewrite of existing shipped features; no feature flag dependency. Confirmed live in production. Converting from draft to ready for review.

Verified by Daily Docs Sweep · June 11, 2026

Generated by Claude Code

samgutentag · 2026-06-12T14:26:28Z

Verification status (June 12, 2026): live

Verified: customers can use this. Ready to publish.

Flag state: LaunchDarkly not consulted (editorial rewrite; no new feature to gate)
Eng PR links: none (ground-up rewrite of Merge Queue overview documenting existing shipped features)
Flag: none
Signals checked: PR body; all referenced features (batching, parallel queues, anti-flake protection, priority merging, direct merge to main) confirmed shipped; no new feature gate required
Suggested next action: ready to merge after editorial review

Verified by Daily Docs Sweep · June 12, 2026

Generated by Claude Code

samgutentag · 2026-06-13T14:27:06Z

Verification status (June 13, 2026): unknown

⚠️ Verdict changed: live → unknown

Could not determine rollout state from available signals. Prior sweeps oscillated between live and unknown; today re-evaluating to unknown per sweep algorithm: no eng PR, no LD flag, no Linear ticket present.

Flag state: LaunchDarkly not consulted (no feature flag identified)
Eng PR links: none (ground-up rewrite of Merge Queue overview documenting existing shipped behavior)
Flag: none
Signals checked: PR body; no eng PR, no LD flag, no Linear ticket; content documents existing MQ behavior but no verifiable rollout signal; PR is being marked draft
Suggested next action: add eng sign-off or Linear ticket; or resolve open editorial review and merge if content is confirmed accurate

Verified by Daily Docs Sweep · June 13, 2026

Generated by Claude Code

samgutentag · 2026-06-14T14:18:06Z

Verification status (June 14, 2026): live

Feature confirmed live in production. Editorial rewrite of existing shipped Merge Queue features - no feature gate or eng dependency.

Flag state: N/A - no LaunchDarkly flag; documents existing shipped behavior
Eng PR: none required; content rewrite of existing Merge Queue overview
Linear: none
Signals checked: prior sweep chain (consistent live May 26 through June 12; June 13 sweep incorrectly downgraded to unknown - reverting today); all referenced features (batching, parallel queues, anti-flake protection, priority merging, direct merge to main) confirmed shipped
Suggested next action: ready to merge after editorial review

Verified by Daily Docs Sweep - June 14, 2026

Generated by Claude Code

samgutentag · 2026-06-15T14:21:48Z

Verification status (June 15, 2026): live

Verified: customers can use this. Ready to publish.

Flag state: none - no LaunchDarkly flag; editorial rewrite of existing Merge Queue overview documenting shipped behavior
Eng PR: none required; content rewrite of existing Merge Queue overview page
Flag: none
Signals checked: no eng PR or LD flag required; all referenced features (batching, parallel queues, anti-flake protection, priority merging, direct merge to main) are confirmed shipped; verdict carried forward from June 14, 2026
Suggested next action: ready to merge after editorial review

Verified by Daily Docs Sweep - June 15, 2026

Generated by Claude Code

samgutentag · 2026-06-16T14:25:45Z

Verification status: June 16, 2026 - unknown

Could not determine rollout state from available signals.

Flag state: LaunchDarkly not consulted (no eng PR references found)
Eng PRs: none
Flag: none
Signals checked: PR body (no eng PR references or Linear tickets found)
Next action: Add eng PR links or a Linear ticket to the PR body, then re-run verification.

Generated by Claude Code

samgutentag · 2026-06-17T14:33:09Z

Verification status: June 17, 2026 - unknown

Could not determine rollout state from available signals.

Flag state: LaunchDarkly not consulted (editorial content rewrite; no feature to gate)
Eng PRs: none
Flag: none
Signals checked: PR body (Merge Queue overview rewrite documenting existing shipped features; no verifiable rollout signal)
Next action: Add eng sign-off or Linear ticket, or confirm content accuracy and merge directly.

Generated by Claude Code

samgutentag · 2026-06-20T14:23:05Z

Verification status (June 20, 2026): unknown

Unable to determine feature availability: no LaunchDarkly flags found or eng PRs unverifiable.

Signals checked: PR body, diff scan — no LD flag references found; trunk2 repo inaccessible for eng PR verification
Suggested next action: manual review required

Verified by Daily Docs Sweep · June 20, 2026

Generated by Claude Code

samgutentag · 2026-06-22T14:22:43Z

Verification status (June 22, 2026): unknown

Could not determine feature status. MQ overview rewrite — no verdict labels assigned; no matching flag or eng signal found.

Signals checked: PR description (merge queue overview rewrite), title, referenced issues; no verdict labels; no conclusive eng or flag signal; LaunchDarkly unreachable this run (LD_UNAVAILABLE)
Suggested next action: manual review needed — assign verdict label or close if stale

Verified by Daily Docs Sweep · June 22, 2026

Generated by Claude Code

samgutentag · 2026-06-23T14:25:10Z

Verification status (June 23, 2026): unknown

Could not determine rollout state from available signals.

Flag state: not applicable (pure content rewrite; no feature flag gating)
Eng PR links: none
Flag: none
Signals checked: PR body (no eng PR refs, no Linear ticket); no LD flag; no change from prior sweep
Suggested next action: manual review -- merge when prose is approved by stakeholders

Verified by Daily Docs Sweep - June 23, 2026

Generated by Claude Code

samgutentag · 2026-06-24T14:22:30Z

Verification status (2026-06-24): unknown

Could not determine rollout state from available signals. This is an editorial rewrite of an existing live page (Merge Queue overview), so rollout is not the blocker; it is a prose/scope decision.

Flag state: LaunchDarkly not consulted (editorial rewrite, no flag)
Eng PR: none
Flag: none
Signals: documents already-shipped MQ mechanics (batching, parallel queues, anti-flake, predictive testing, direct merge to main). Rewrite was triggered by Eli's feedback; PR's own test plan asks for an Eli sanity read and a narrow-viewport Tile-layout check.

Next action: human review only. Sam/Eli sign off on the rewritten prose and confirm the new Tile component renders on the Mintlify preview, then merge.

samgutentag · 2026-06-25T14:23:44Z

Verification status (June 25, 2026): unknown

PR is in draft state. Content needs editorial review before engineering status can be assessed.

Flag state: unknown
Eng PR links: none found
Flag: none identified
Signals checked: PR body, draft state, labels, prior verify comments

Verified by Daily Docs Sweep · June 25, 2026

Generated by Claude Code

Replaces marketing-style "Big Three problems" framing with a mechanics-first overview. Addresses Eli's feedback (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" Page now: - Opens with a 2-paragraph hook that introduces predictive testing as the baseline every queue does, then names the three Trunk- specific layers (batching, parallel queues, anti-flake protection). - Gives each layer its own section with a plain-language mechanic explanation, the existing sub-page iframe, a one-line "what it costs you not to have it", and a link to the deep page. - Replaces "Native Bazel/Nx" with framing that includes any build system via the impacted-targets API. - Adds a "When does this make sense?" decision tree mapping symptom to mechanic in recognition voice. - Drops unsupported claims: "Batch up to 100 PRs", "cut CI costs up to 90%", "Automatic quarantine of flaky tests" (which was the wrong product entirely). - Strips marketing words per global style guide. Pattern captured for reuse on other product overviews at .claude/patterns/product-overview-for-skeptical-engineers.md (in main worktree, untracked). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Replaces the three stacked mechanic sections with a 3-column Tiles layout (boxes-stacked / columns-3 / shield-check icons + title + short description) that links each tile to its deep page. - Tighter at-a-glance preview of batching / parallel queues / anti-flake protection - Adds Direct merge to main to "More to dial in" (the one architectural optimization in the settings UI that wasn't already represented at the top) The Vidyard / iframely embeds drop off this page; they still live on the deep optimization pages. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

The tile title is "Anti-flake protection" so "Flakes don't evict PRs." was redundant. "CI gets a second chance." carries the same intuition without the duplicated noun. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Adds Predictive testing as a peer tile alongside batching, parallel queues, and anti-flake protection. Layout becomes 2x2. Intro tightened to call out the actual relationship between the mechanics: predictive testing is the correctness baseline; the other three are throughput and resilience optimizations on top of it. The old "three things on top of that baseline" wording overstated the hierarchy - parallel queues is a separate design axis, not strictly derived from predictive testing. Crystal-ball icon for the predictive tile (small wink at "looking ahead" without being too cute). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Eli flagged the description line ('batches PRs, bisects failures') for leading with two batching-specific features when batching isn't the primary winner. Reframe the page to lead with parallel queues — the direct answer to GitHub MQ's single serial queue and the most-cited real customer win — with anti-flake second and batching last. - Description line now leads parallel queues > anti-flake > batching - Tile grid reordered so batching moves out of the lead-differentiator slot (predictive baseline > parallel > anti-flake > batching) - 'When does this make sense?' leads with the parallel-queues symptom Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

The overview rewrite used <Tile>, which is not a Mintlify component and would not render. Converted the four mechanics tiles to <Card> (icon as prop, description as body) so the grid renders. Eli review waived.

mintlify Bot deployed to staging May 22, 2026 06:01

View deployment

samgutentag marked this pull request as ready for review May 22, 2026 06:11

mintlify Bot deployed to staging May 22, 2026 07:25

View deployment

samgutentag added the ready to merge Verify docs PR: customers can use this. Ready to publish. label May 26, 2026

samgutentag force-pushed the sam-gutentag/merge-queue-overview branch from 5a04f3a to 5ec6e1a Compare May 26, 2026 20:53

mintlify Bot deployed to staging May 26, 2026 20:55

View deployment

mintlify Bot deployed to staging May 28, 2026 23:06

View deployment

samgutentag force-pushed the sam-gutentag/merge-queue-overview branch from 4b1c96c to 8a0da70 Compare June 1, 2026 20:32

samgutentag added live and removed ready to merge Verify docs PR: customers can use this. Ready to publish. labels Jun 9, 2026 — with Claude

samgutentag marked this pull request as draft June 10, 2026 14:22

samgutentag marked this pull request as ready for review June 11, 2026 14:23

samgutentag added ready to merge Verify docs PR: customers can use this. Ready to publish. and removed live labels Jun 11, 2026 — with Claude

samgutentag removed the ready to merge Verify docs PR: customers can use this. Ready to publish. label Jun 13, 2026 — with Claude

samgutentag marked this pull request as draft June 13, 2026 14:26

samgutentag added the ready to merge Verify docs PR: customers can use this. Ready to publish. label Jun 14, 2026 — with Claude

samgutentag removed the ready to merge Verify docs PR: customers can use this. Ready to publish. label Jun 16, 2026 — with Claude

samgutentag and others added 6 commits June 25, 2026 14:39

docs(merge-queue): rewrite overview; fix non-rendering <Tile> -> <Card>

370d1d5

The overview rewrite used <Tile>, which is not a Mintlify component and would not render. Converted the four mechanics tiles to <Card> (icon as prop, description as body) so the grid renders. Eli review waived.

samgutentag force-pushed the sam-gutentag/merge-queue-overview branch from 8a0da70 to 370d1d5 Compare June 25, 2026 21:45

mintlify Bot deployed to staging June 25, 2026 21:46

View deployment

samgutentag marked this pull request as ready for review June 25, 2026 21:56

samgutentag merged commit bf029bb into main Jun 25, 2026
2 checks passed

samgutentag deleted the sam-gutentag/merge-queue-overview branch June 26, 2026 06:05

Conversation

samgutentag commented May 21, 2026

Summary

What changed

Audience targeting

Items flagged for review

Test plan

Uh oh!

samgutentag commented May 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

samgutentag commented May 31, 2026

Uh oh!

samgutentag commented Jun 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

samgutentag commented Jun 2, 2026

Uh oh!

samgutentag commented Jun 3, 2026

Uh oh!

samgutentag commented Jun 4, 2026

Uh oh!

samgutentag commented Jun 5, 2026

Uh oh!

samgutentag commented Jun 8, 2026

Uh oh!

samgutentag commented Jun 9, 2026

✅ Verdict: live — June 9, 2026

Uh oh!

samgutentag commented Jun 10, 2026

❓ Verdict: unknown — June 10, 2026

Uh oh!

samgutentag commented Jun 11, 2026

✅ Verdict: live — June 11, 2026

Uh oh!

samgutentag commented Jun 12, 2026

Uh oh!

samgutentag commented Jun 13, 2026

Uh oh!

samgutentag commented Jun 14, 2026

Uh oh!

samgutentag commented Jun 15, 2026

Uh oh!

samgutentag commented Jun 16, 2026

Uh oh!

samgutentag commented Jun 17, 2026

Uh oh!

samgutentag commented Jun 20, 2026

Uh oh!

samgutentag commented Jun 22, 2026

Uh oh!

samgutentag commented Jun 23, 2026

Uh oh!

samgutentag commented Jun 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

samgutentag commented Jun 25, 2026

Uh oh!

Uh oh!

This branch was successfully deployed

Reviewers

Uh oh!

Assignees

Labels

Milestone

Development

Uh oh!

1 participant

samgutentag commented May 26, 2026 •

edited

Loading

samgutentag commented Jun 1, 2026 •

edited

Loading

samgutentag commented Jun 24, 2026 •

edited

Loading