docs: require a user flow and a stuck-at proof in feature requests

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -24,10 +24,61 @@ body:
     validations:
       required: true
   - type: textarea
-    id: motivation
+    id: user-flow
     attributes:
-      label: Motivation, pitch
-      description: Please outline the motivation for the proposal. Is your feature request related to a specific problem? e.g., "I'm working on X and would like Y to be possible". If this is related to another GitHub issue, please link here too.
+      label: User Flow
+      description: Two numbered lists walking the same end user through the same task, one today without the feature and one with it. Keep the guidance comments in the box while you fill it in, they explain every rule.
+      value: |
+        <!-- Two ordered lists, "Today (without the feature)" and "With the feature", walking the same end user through the same task, written strictly from that user's seat
+             Describe the real application and the routes its users actually hit, not a generic scenario. Link any related GitHub issue or provider API docs
+             Lead each list with one plain sentence saying where the flow dead-ends today and what it would let them do instead, then number the steps
+             Every step is something the user does or observes: the HTTP method and full URL they hit, what they sent, and what visibly came back (status code, error text, the shape of an ID). UI steps name the page URL and what is on screen
+             No LiteLLM internals: never name functions, files, DB tables, config classes, hooks, callbacks, or code paths. Ask for the behavior you need, not the implementation you imagine
+             Keep the two lists step-for-step identical until they diverge, so the missing capability is obvious
+             "Today" is also where you show the workaround you're living with, which is what tells us how badly this is needed
+
+        Example:
+
+        Today (without the feature): a developer batching nightly summaries has no way to mark those calls as low priority, so they compete with live traffic for the same rate limit
+
+        1. They send POST https://litellm-domain/v1/chat/completions for 500 documents in a loop
+        2. Around document 120 they start getting 429s naming the rpm limit, and their user-facing chat app starts getting them too
+        3. Their workaround is a hand-rolled sleep between calls, which stretches the batch to 3 hours and still collides at peak
+
+        With the feature: the same batch runs as background work that yields to live traffic
+
+        1. The developer sends the same POST with `"service_tier": "flex"`
+        2. Batch calls queue behind interactive ones instead of 429ing, and the response comes back with the tier it was served at
+        3. The live chat app keeps returning 200s throughout the batch
+        4. https://litellm-domain/ui/?page=logs shows the batch requests tagged with that tier
+        -->
+
+        Today (without the feature): 
+
+        1. 
+        2. 
+        3. 
+
+        With the feature: 
+
+        1. 
+        2. 
+        3. 
+    validations:
+      required: true
+  - type: textarea
+    id: how-far-you-got
+    attributes:
+      label: How far you got
+      description: Walk the "With the feature" list against a live proxy and paste the commands and output up to the step where you get stuck. Keep the guidance comments in the box while you fill it in, they explain every rule.
+      value: |
+        <!-- Run as many steps of the "With the feature" list as you can against a live proxy you ran yourself (e.g., litellm --config config.yaml --detailed_debug on localhost:4000), then paste the commands (e.g., curl) and their full output, ending at the step that dead-ends
+             Say plainly what stopped you there, in user terms: the option you passed came back ignored, the response 400'd naming an unsupported field, there is no button on the page for it. This is what proves the feature is genuinely missing rather than undocumented, and it is the single most useful thing you can give us
+             No mocks. Where the flow involves a provider call, hit the real provider API, even though that costs real $. `pytest` commands are not enough
+             Include the config.yaml (or SDK setup) and env vars the proxy ran with, plus the version or commit you were on. Keep the real values for env vars that aren't sensitive, and redact only the secrets: never paste a real API key, virtual key, database URL, or other credential, here or anywhere else in the issue
+             If the provider already supports this, link their API docs and paste a direct call to them succeeding, so we can see the shape LiteLLM should be sending
+             For UI asks: include screenshots of the page you got stuck on and its URL. Scrub keys and tokens out of screenshots too, they show up in headers, request panels, and the Admin UI -->
+
     validations:
       required: true
   - type: dropdown

CLAUDE.md

@@ -31,7 +31,7 @@ When creating PRs, don't set base to `main`. `litellm_internal_staging` is the d
 
 When writing a PR body, treat the comments and imperative instructions inside @.github/pull_request_template.md as rules to follow, not just layout. Agent harnesses may strip HTML comments from copies of that file injected into context, so read .github/pull_request_template.md from disk before writing a PR body to make sure you see every comment rule
 
-Same applies for filing bug reports and .github/ISSUE_TEMPLATE/bug_report.yml
+Same applies for filing bug reports and feature requests, and .github/ISSUE_TEMPLATE/bug_report.yml and .github/ISSUE_TEMPLATE/feature_request.yml
 
 If you're resolving a linear ticket, in the "## Linear ticket" section of the PR, say "Resolves LIT-1234", replacing "LIT-1234" with the actual ticket id that you're resolving. If you don't have the ticket id, don't make one up or search for it. Just leave the section blank