docs: clarify PR caveat severity and merge dependencies

.github/PULL_REQUEST_TEMPLATE/general.md

@@ -4,6 +4,13 @@
      Drop every section you have nothing to put in, heading included: a bare "## Relevant issues" or
      "## Affected release" with nothing under it must not appear in the final description -->
 
+## Merge blockers and dependencies
+
+<!-- Follow .github/pr-caveats.md for classification and dependency verification
+     List unresolved prerequisites here before the TLDR: exact PR links/actions, what breaks,
+     merge or rollout order, owner, and verified status. Identify canonical/replacement PRs when
+     duplicates exist. Do not merge until satisfied; drop this section only when none remain -->
+
 ## TLDR
 
 <!-- Fill in the bullets below and keep each one short and concrete: one line per bullet, roughly 10 words max
@@ -19,6 +26,13 @@ How it solves it:
 - <blah>
 - ...
 
+## Caveats (if any)
+
+<!-- Classify caveats using .github/pr-caveats.md, by impact rather than fix size
+     Use only nonempty ### Severe, ### High, ### Medium, and ### Low tiers, in that order
+     Keep bullets short, with consequences and mitigations. Put unresolved prerequisites
+     in Merge blockers and dependencies above, never only under Low. Drop this section if empty -->
+
 ## User Flow
 
 <!-- Two ordered lists, Before and After, walking the same end user through the same task, written strictly from that user's seat
@@ -121,26 +135,6 @@ If you're seeing a delay in your PR being merged, ping the LiteLLM Team on [Slac
 🚄 Infrastructure
 ✅ Test
 
-## Caveats (if any)
-
-<!-- Group caveats under severity subheadings (### Severe, ### High, ### Medium, ### Low), with
-     short bullet points inside each, just like the TLDR: one line per bullet, roughly 10 words max
-     Call out known limitations, follow-up work, or anything a reviewer should watch out for
-     Include only the tiers that have caveats; drop the empty ones
-     - Severe: inherent to what the PR deliberately ships, there even when the code works as intended:
-       it can degrade or take down a running deployment (e.g. a slow or table-locking boot migration),
-       rewrite data by design, break an existing workflow on purpose, or change auth behavior. An
-       operator must plan around it before rollout
-     - High: an unintended hole: a correctness, security, data-loss, or backward-compatibility bug,
-       unsafe to ship as is
-     - Medium: a real gap someone can hit, but with a workaround or a narrow blast radius
-     - Low: anything else worth noting: naming, cleanup, an edge case nobody hits
-     Nest bullets as deep as helps: hierarchy beats one long line when it makes things clearer to a
-     human reader
-     If you assumed something instead of testing it, e.g. "only reproduces with X on" or "no
-     user-observable behavior difference", list it here too with what breaks if it is wrong
-     Drop this section if there are none -->
-
 ## QA runbook
 
 <!-- Only needed when your PR edits tests/e2e; delete this section otherwise

.github/PULL_REQUEST_TEMPLATE/rust.md

@@ -1 +1,7 @@
-<!-- Write the final PR description as concise bullets only -->
+<!-- Write the final PR description as concise bullets only
+     Follow .github/pr-caveats.md for caveat classification and dependency verification
+     Lead with unresolved merge blockers: exact prerequisite PR links/actions, what breaks,
+     merge or rollout order, owner, and verified status. Identify canonical/replacement PRs
+     when duplicates exist. Do not merge until prerequisites are verified as satisfied
+     Put remaining caveats immediately after the summary, labeled Severe, High, Medium, or Low
+     Omit empty sections -->

.github/pr-caveats.md

@@ -0,0 +1,37 @@
+# PR caveats and merge dependencies
+
+Classify by what happens if the caveat is ignored, not by the size of the diff, the effort to fix it, or whether the change is intentional. A one-line docs fix can still block a merge if CI depends on it
+
+## Merge blockers and dependencies
+
+Put unresolved merge prerequisites in `## Merge blockers and dependencies` before the TLDR, not only in Caveats or Relevant issues. Do not merge until the prerequisites are verified as satisfied
+
+For each prerequisite, record:
+
+- The exact PR URL or required action, including the repository for cross-repository dependencies
+- What breaks without it, such as CI, a docs build, runtime behavior, or deployment
+- The required merge or rollout order and who owns the next action
+- Its verified status: pending, merged, deployed, or unknown, with supporting evidence. Unknown means unresolved; merged does not mean deployed
+
+If duplicate or replacement PRs exist, identify the canonical PR and explicitly link which PR it supersedes. Verify that the required change landed on the intended branch; matching titles, identical-looking diffs, or a closed PR are not proof that the dependency is satisfied. If an equivalent duplicate landed instead, verify its contents and target branch and update the dependency link to that PR
+
+Keep this section current as dependencies change. Remove it only when all prerequisites are verified as satisfied, or when there are none. Keep any remaining rollout risks in Caveats
+
+Example: a code PR requires a companion docs PR to keep the docs build passing. This is a merge blocker until the required docs change is verified on the branch the build uses, even if the docs patch is one line
+
+## Caveat severity
+
+Put `## Caveats (if any)` immediately after the TLDR so reviewers see remaining risks before the detailed description. Group short bullets under the following headings, highest severity first, and omit empty tiers
+
+| Tier | Classification | Examples / required action |
+| --- | --- | --- |
+| Severe | A change can take down or substantially degrade a deployment, rewrite or lose data, break an existing workflow, or change authentication or authorization behavior | A table-locking boot migration or an intentional auth change needs an explicit rollout plan before shipping |
+| High | A correctness, security, data-loss, or backward-compatibility defect makes the change unsafe to ship, even with a narrow blast radius | An auth bypass for one route or incorrect results for one supported configuration must be fixed before shipping |
+| Medium | A bounded, non-security limitation with a verified safe workaround, where merging independently keeps CI and supported deployments working | An optional feature has a documented limitation and a tested alternative |
+| Low | Informational or cosmetic follow-up with no effect on correctness, security, CI, compatibility, or rollout order | Naming cleanup or optional explanatory docs |
+
+Use the highest applicable tier. Intentional changes are not automatically safer, and rarity alone does not make an issue Low. Security and data-loss risks never become Medium or Low merely because they affect few users or have a workaround
+
+Merge readiness is separate from severity: any unresolved prerequisite or unsafe-to-ship defect also belongs in the top merge-blocker section. Required companion PRs, migrations, configuration changes, and release coordination must never be buried under Low
+
+For each caveat, state the affected behavior, consequence, and mitigation or follow-up. Link follow-up work when it exists. If a claim is assumed rather than tested, identify the missing verification and classify by what breaks if the assumption is wrong; do not describe an unverified workaround as safe