[feature not live] docs(flaky-tests): document automatic labeling from monitors

[samgutentag]

Summary

• Replaces the 'Coming soon' placeholder in flaky-tests/test-labels.md with live documentation for monitor label actions (auto-apply/remove labels on activation/resolution)
• Documents label cleanup behavior on monitor delete/disable and label set changes
• Notes the guard on deleting labels in use by active monitors

Source

• trunk2 PR: https://github.com/trunk-io/trunk2/pull/3774

Test plan

• Preview in GitBook

---

Generated by Claude Code

[trunk-staging-io]

Merging to main in this repository is managed by Trunk.

• To merge this pull request, check the box to the left or comment /trunk merge below.

After your PR is submitted to the merge queue, this comment will be automatically updated with its status. If the PR fails, failure details will also be posted here

[claude]

Claude finished @samgutentag's task in 54s —— View job

---

PR Review

• Gather context
• Read changed file and diff
• Review for typos, grammar, formatting, and documentation best practices
• Post feedback

---

The new content is clear, well-structured, and follows the existing doc style. Two issues found:

Blocking — stale intro text (flaky-tests/test-labels.md, line 7)

The intro paragraph was not updated when the "Coming soon" placeholder was replaced. It currently reads:

"Labels are applied manually today; see Automatic labeling from monitors for what's coming."

The phrase "what's coming" is no longer accurate. Suggested fix:

"Test labels are organization-scoped tags you can apply to individual test cases to organize, filter, and categorize your test suite. Labels can also be applied automatically via monitors; see Automatic labeling from monitors."

Fix this →

Minor — missing article (line 43, inline comment posted)

"any labels that monitor had applied" → "any labels that the monitor had applied"

[claude]

Missing article — "that monitor" should be "that the monitor".

Suggested change

	- **When you disable or delete a monitor:** any labels that monitor had applied are automatically removed from all affected test cases.
	- **When you disable or delete a monitor:** any labels that the monitor had applied are automatically removed from all affected test cases.

[samgutentag]

Triage status (2026-05-05): up to date with main. Needs review before merge.

[claude]

Claude finished @samgutentag's task in 58s —— View job

---

PR Review

• Gather context (read latest file + diff)
• Verify previous review feedback was addressed
• Review for typos, grammar, formatting, style
• Post feedback

---

The latest revision did not address the two issues flagged in the previous review. Both are still present on this branch.

Blocking — stale intro text (flaky-tests/test-labels.md:7)

The opening paragraph still describes the feature as "what's coming":

"Labels are applied manually today; see Automatic labeling from monitors for what's coming."

Now that monitor-driven labeling is documented as a live capability in this same page, this intro contradicts the body. Suggested replacement:

"Test labels are organization-scoped tags you can apply to individual test cases to organize, filter, and categorize your test suite. Labels can also be applied automatically via monitors; see Automatic labeling from monitors."

Fix this →

Minor — missing article (flaky-tests/test-labels.md:43)

"any labels that monitor had applied" → "any labels that the monitor had applied"

Fix this →

Minor — capitalization inconsistency in cleanup bullets (lines 43–44)

The first two bullets share the "When you …: explanation" pattern but capitalize the body text differently:

• Line 43: "When you disable or delete a monitor: any labels that..." (lowercase)
• Line 44: "When you change the label set on a monitor's label action: Trunk reconciles..." (capitalized)

Pick one — capitalizing the start of a sentence after the bold colon (matching line 44) is more conventional. So line 43 would become "...monitor:** Any labels that the monitor had applied..."

---

Once the line 7 stale phrasing is fixed, this is good to go. The new content itself reads cleanly and matches the existing page style.
• Branch

[samgutentag]

Verification status (2026-05-07, re-verified): pending

Eng merged but flag off in prod. Hold off.

• Eng PR: trunk2#3774 ("Configure label actions on monitors", merged 2026-05-04, merge commit still on main)
• Linear ticket: none referenced
• Flag: showLabelActions
• Signals (re-checked today):
  • Flag still has 5 hits in trunk2 main (flags.ts, e2e/flags.json, monitor/page.tsx, monitor-flags-context.tsx, monitor-actions-section.tsx). LaunchDarkly URL still active in flags.ts.
  • No "rollout/100%/delete legacy/remove flag" PRs. The only PR mentioning showLabelActions is the eng PR itself (#3774). Verified via gh search prs.
  • No new rollout signal since yesterday.

Branch state: 1 commit ahead of yesterday with the review-fix commit 98d9f72.

Review nits applied (didn't wait for rollout, since these are content fixes that should land regardless):

• Line 7: dropped the stale "for what's coming" framing that contradicted the body of the page. Reworded to "Labels can also be applied automatically via monitors; see [Automatic labeling from monitors]" which reads correctly regardless of rollout state.
• Line 43: added the missing article ("any labels that the monitor had applied") and capitalized "Any" for consistency with the second cleanup bullet's sentence-case-after-colon pattern.

trunk check clean. PR stays in draft per pending verdict.

Suggested next action: re-run /verify-docs-pr 594 once a follow-up PR removes showLabelActions from flags.ts, or once a Slack message confirms 100% prod rollout.

[claude]

Claude finished @samgutentag's task in 55s —— View job

---

PR Review

• Gather context
• Read current file + diff
• Verify previous review feedback was addressed
• Review for typos, grammar, formatting, style
• Post feedback

---

All three previously flagged issues are resolved in 98d9f72:

• Line 7 — stale "for what's coming" framing replaced with "Labels can also be applied automatically via monitors; see [Automatic labeling from monitors]." ✅
• Line 43 — missing article added: "any labels that the monitor had applied" ✅
• Line 43 — "Any" capitalized so the cleanup bullets share sentence-case-after-colon with line 44 ✅

Spot check on the rest of the page

• The new section reads cleanly and fits the existing tone.
• Heading hierarchy (H1 → H3 → H4 inside Automatic labeling from monitors) matches the rest of the file.
• The third bullet under "How label cleanup works" (line 45) uses a slightly different shape than the first two — **Deleting a label is blocked** if it is still configured… vs. **When you …:** explanation. This is intentional-looking (it's a guard-rail rather than a cleanup behavior), and the meaning is clear, so not worth restructuring. Flagging only as an FYI.

Verification status (unchanged from author's note)

The eng PR (trunk2#3774) is merged but showLabelActions is still gated in prod. The author has chosen — correctly, in my read — to land the content fixes now and keep this PR in draft until rollout, since the wording fixes are independent of feature state.

✅ No blocking issues. Good to keep parked in draft pending the LD flag rollout.
• Branch

[github-actions]

Auto-approved: Claude code review passed.