docs(workflow): require PRs to mirror their closing issue's triage labels (closes #237)

[cristim]

Summary

• Closes docs(workflow): require PRs to mirror their closing issue's triage labels #237: codifies three mandatory workflow rules that were present in the system-prompt CLAUDE.md but absent from the feat/multicloud-web-frontend base branch.
• Post-push CI watcher — arm a background watcher after every git push so CI failures surface within the same turn.
• CodeRabbit loop — iterate CR passes until zero Actionable items remain before declaring a PR done.
• PR labeling — mirror the closing issue's triage labels (priority/*, severity/*, urgency/*, impact/*, effort/*, type/*, triaged) onto every new PR via gh pr edit --add-label, before pinging CodeRabbit. Unlabeled PRs are invisible to priority-ordered is:open label:priority/p* queries.

The silent failure that motivated this PR: 10 PRs shipped in two recent batches, all merged-eligible after CR sign-off, none labeled — making them invisible to triage ordering.

Dogfooding

This PR itself is labeled with the issue's triage labels per the new rule (type/docs, priority/p3, severity/low, urgency/eventually, impact/internal, effort/xs, triaged).

Test plan

• CLAUDE.md contains ## PR labeling — mirror closing-issue labels (MANDATORY) between ## CodeRabbit loop and ## Security Rules
• Section includes the gh invocation with jq filter for all label classes
• Multi-close handling (highest priority/severity, union the rest) is documented
• No-triaged-lie rule is present
• Closing checkpoint paragraph matches the CI-watcher pattern
• Post-push CI watcher and CodeRabbit loop sections also present (they were absent from base branch)

Summary by CodeRabbit

• Documentation
  • Added mandatory CI monitoring and automated follow-up procedure to detect and surface failing runs and trigger corrective pushes when appropriate.
  • Introduced a mandatory iterative review loop with explicit triage and batching rules for findings, requiring repetition until actionable items and nitpicks are addressed or justified.
  • Established PR labeling rules to ensure labels mirror associated issue triage and added verification steps for applying labels.

[coderabbitai]

Warning

Review limit reached

@cristim, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 10 minutes and 26 seconds. Learn how PR review limits work.

Your organization has used up its prepaid credits, and credit purchases are no longer available. Enable the review add-on in the billing tab to keep reviews running — you're only billed for reviews past your plan's rate limits ($0.25/file).

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based credits.

🚦 How do rate limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan refill rate.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, the refill rate gradually slows as usage increases. The highest same-day bursts are limited more strictly.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 5de00298-81d5-4a03-9121-c43296852f76

📥 Commits

Reviewing files that changed from the base of the PR and between 64fc92a and c3ae487.

📒 Files selected for processing (1)

• CLAUDE.md

📝 Walkthrough

Walkthrough

Documentation adds three mandatory workflow procedures to CLAUDE.md: a post-push CI watcher that arms background watchers and can auto-fix failures; a CodeRabbit review loop with triage and repeat-until-clean rules; and a PR-labeling procedure that mirrors closing-issue triage labels via gh.

Changes

Workflow Procedure Documentation

Layer / File(s)	Summary
Post-Push CI Watcher CLAUDE.md	Procedure for listing GitHub Actions runs triggered by a push, launching background watchers for queued/in_progress runs, reporting failures (failed step digests), and automatically pushing fixes. Includes a checkpoint verifying at least one ci-watch-* background task is armed before concluding.
CodeRabbit Review Loop CLAUDE.md	Mandatory review loop requiring deterministic @coderabbitai review triggering, polling/soft-handling expectations, triage classification (Actionable/Outside-diff/Nitpick), batching rules for nitpicks, fix-push and re-ping mechanics, conflict handling (rebase/force-with-lease), and loop-exit criteria requiring zero Actionable items and resolved/justified nitpicks.
PR Labeling — Mirror Closing Issue CLAUDE.md	Rules to mirror closing-issue triage labels (priority/severity/urgency/impact/effort/type and optional triaged) during gh pr create, verification commands to confirm applied labels, label creation when missing, multi-issue unioning with highest priority/severity selection, and a pre-completion confirmation that PR labels match the closing-set.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Suggested labels

priority/p2, severity/medium, urgency/this-sprint, effort/s, type/chore

"I’m a rabbit with a checklist bright,
CI watches keep the night in sight,
CodeRabbit hops and pings again,
Labels echo issues’ ken,
A tiny push, a tidy flight."

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically describes the main change: adding a mandatory rule requiring PRs to mirror their closing issue's triage labels, with issue reference.
Linked Issues check	✅ Passed	All acceptance criteria from issue #237 are met: CLAUDE.md contains the mandatory PR labeling section with exact gh invocation, multi-close handling, cross-references with existing sections, and matching checkpoint language.
Out of Scope Changes check	✅ Passed	All changes are within scope: documentation updates to CLAUDE.md include the required PR labeling section plus complementary updates to CR-loop and CI-watcher sections for cross-referencing.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/issue-237-codify-pr-labeling

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[cristim]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

CLAUDE.md (1)

150-153: ⚡ Quick win

Avoid manual PR_NUM entry in a mandatory path.

Using a hand-copied PR number is brittle and easy to misapply to the wrong PR. Prefer deriving it directly from the current branch context.

Safer PR number resolution

-PR_NUM=<the number gh just printed>
+PR_NUM=$(gh pr view --repo LeanerCloud/CUDly --json number --jq '.number')
 ISSUE_NUM=<the issue this PR closes>

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@CLAUDE.md` around lines 150 - 153, Replace the brittle manual PR_NUM
assignment after `gh pr create` with automatic resolution: capture the created
PR number programmatically (e.g., parse `gh pr create` output or call `gh pr
view` for the current branch) and set PR_NUM from that value; reference the
variables PR_NUM and ISSUE_NUM and the command `gh pr create` in your changes so
the script derives PR_NUM from the current branch/PR context rather than
requiring manual entry.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@CLAUDE.md`:
- Around line 154-160: The script currently unconditionally runs gh pr edit
"$PR_NUM" --add-label "$LABELS", which fails when LABELS is empty; change it to
guard the call by checking the LABELS variable first (the LABELS assignment and
the gh pr edit "$PR_NUM" --add-label "$LABELS" invocation), e.g., only call gh
pr edit with --add-label when LABELS is non-empty and otherwise surface the
triage gap deterministically (for example add a specific fallback label like
"triage-needed" or post a comment) so the workflow does not break on empty label
payloads.

---

Nitpick comments:
In `@CLAUDE.md`:
- Around line 150-153: Replace the brittle manual PR_NUM assignment after `gh pr
create` with automatic resolution: capture the created PR number
programmatically (e.g., parse `gh pr create` output or call `gh pr view` for the
current branch) and set PR_NUM from that value; reference the variables PR_NUM
and ISSUE_NUM and the command `gh pr create` in your changes so the script
derives PR_NUM from the current branch/PR context rather than requiring manual
entry.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 00bc1995-90e3-4a99-982a-b2b93e9aaacd

📥 Commits

Reviewing files that changed from the base of the PR and between c84fd02 and 7dbe911.

📒 Files selected for processing (1)

• CLAUDE.md

[cristim]

Added a follow-up commit (188012004) extending the CR-loop section with explicit subagent-delegation guidance — exit criteria for fork prompts, not just human workflows. Surfaced by the catch-up CR-loop pass on PRs #227–#236 (none of those forks ran the CR loop because my prompts stopped at the @coderabbitai review ping). @coderabbitai review

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

@cristim: Understood — triggering a review pass to cover commit 188012004 and the subagent-delegation exit-criteria additions to the CR-loop section.

[review]

[cristim]

CodeRabbit pass 1 — both findings addressed

Pushed commit 64fc92a addressing both items from the 2026-05-03 review:

Actionable (Major) — empty $LABELS guard

Fixed. gh pr edit --add-label "" does fail (silently breaks the MANDATORY flow), so I added an if [ -n "$LABELS" ] guard with a clear WARN fallback that names the missing classes and tells the operator to triage the issue first. Matches your proposed hardening with slightly more informative output (the WARN message explicitly references the issue number and the expected label classes, so the operator knows what's missing without re-reading CLAUDE.md).

Nitpick (Quick win) — manual PR_NUM entry

Fixed. Replaced PR_NUM=<the number gh just printed> with PR_NUM=$(gh pr view --repo LeanerCloud/CUDly --json number --jq '.number') exactly as you suggested. Removes the hand-copy step entirely — the snippet now works without any operator edits after gh pr create (since gh pr view defaults to the current branch).

ISSUE_NUM is intentionally kept as a placeholder — there's no reliable way to auto-derive the closing-issue number from the branch alone, and the PR body's Closes #N line isn't structured enough to parse safely. The operator still has to fill that in once.

CI green on the previous head; watchers armed for 64fc92a. No behavioural changes to the happy path.

@coderabbitai full review

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Fetch the CLAUDE.md from the PR branch
git log --oneline -8
echo "---"
cat CLAUDE.md

Length of output: 19004

---

@cristim: Full review complete on commits 7dbe911 + 1880120 + 64fc92a. Both prior findings are cleanly resolved and the three new CLAUDE.md sections satisfy all acceptance criteria from #237.

---

Review summary

✅ Empty $LABELS guard (was Actionable/Major)

The if [ -n "$LABELS" ] guard is correct. When the closing issue has no labels in the selected classes, jq's join(",") on an empty array produces "", which fails [ -n "" ], and the WARN path fires with a message that names the issue number and the expected label classes. No silent breakage of the MANDATORY flow.

✅ PR_NUM auto-derivation (was Nitpick)

PR_NUM=$(gh pr view --repo LeanerCloud/CUDly --json number --jq '.number') is correct. gh pr view defaults to the current branch's PR (which exists by the time this runs, since it's post–gh pr create). The hand-copy step is gone.

✅ ISSUE_NUM as intentional placeholder

Keeping ISSUE_NUM=<the issue this PR closes> is the right call. There is no reliable machine-parseable link between a branch name and its closing issue number, and parsing the PR body's Closes #N`` line is fragile at creation time. One manual fill-in is a reasonable trade-off.

✅ jq filter correctness

[.labels[].name | select(test("^(priority|severity|urgency|impact|effort|type)/")) ]
+ (if [.labels[].name] | any(. == "triaged") then ["triaged"] else [] end)
| join(",")

• any(. == "triaged") desugars to any(.[]; . == "triaged") — valid jq, correctly detects the triaged label.
• gh issue view --json labels always returns a labels array (never null), so no null-dereference risk.
• join(",") on the concatenated array produces a gh pr edit --add-label-compatible comma-separated string.

✅ Acceptance criteria from #237

Criterion	Status
"PR labeling — mirror closing-issue labels (MANDATORY)" section	✅
Exact gh invocation with jq filter for all label classes	✅
Multi-close handling (highest priority/severity, union rest)	✅
No-triaged-lie rule	✅
"Before declaring done" checkpoint mirrors CI-watcher pattern	✅
Post-push CI watcher section present	✅
CodeRabbit loop section present	✅
Subagent-delegation exit criteria in CR-loop	✅

---

No actionable items remain. The PR is ready to merge.

[approve]

[cristim]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[cristim]

@coderabbitai resolve

[coderabbitai]

✅ Actions performed

Comments resolved. Approval is disabled; enable reviews.request_changes_workflow to allow explicit top-level @coderabbitai resolve or @coderabbitai approve commands.

[cristim]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[cristim]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[cristim]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[cristim]

CR finding verification - PR_NUM auto-derivation

Both findings from the CodeRabbit review (2026-05-03) against commit 7dbe911 are already addressed in commit 64fc92a:

Nitpick (lines 150-153): brittle manual PR_NUM
Fixed by replacing PR_NUM=<the number gh just printed> with:

PR_NUM=$(gh pr view --repo LeanerCloud/CUDly --json number --jq '.number')

This derives the PR number automatically from the current branch context.

Major (lines 165-180): unconditional gh pr edit --add-label on empty LABELS
Fixed by guarding with if [ -n "$LABELS" ] and printing a deterministic warning when no matching triage labels exist on the closing issue.

No new commits are needed. Current HEAD is 64fc92a on branch docs/issue-237-codify-pr-labeling.

@coderabbitai review

[coderabbitai]

@cristim: Confirmed — your verification summary matches the conclusions from the full review pass on 64fc92a:

• Nitpick (lines 150–153): PR_NUM auto-derivation via gh pr view --repo LeanerCloud/CUDly --json number --jq '.number' correctly resolves the hand-copy fragility. ✅
• Major (lines 165–180): The if [ -n "$LABELS" ] guard with the informative WARN path (naming the issue number and expected label classes) correctly prevents silent failure on an empty label set. ✅

Both fixes were already validated in the prior review, all acceptance criteria from #237 are satisfied, and no actionable items remain. Triggering a fresh incremental pass to cover the current HEAD.

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[cristim]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[cristim]

@coderabbitai review

[coderabbitai]

Rate Limit Exceeded

@cristim have exceeded the limit for the number of chat messages per hour. Please wait 38 minutes and 37 seconds before sending another message.

[cristim]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[cristim]

@coderabbitai full review

[coderabbitai]

✅ Action performed

Full review finished.

[cristim]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.