docs: require a user flow and live-proxy proof in bug reports

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

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -27,26 +27,64 @@ body:
     validations:
       required: true
   - type: textarea
-    id: steps-to-reproduce
+    id: user-flow
     attributes:
-      label: Steps to Reproduce
-      description: Please provide a numbered list of the exact steps to reproduce this bug (include a curl/python snippet to reproduce it). Number each step (1., 2., 3., ...) in the order you performed them.
-      placeholder: |
-        1. config.yaml file/ .env file/ etc.
-        2. Run the following code...
-        3. Observe the error...
+      label: User Flow
+      description: Two numbered lists walking the same end user through the same task, one before a hypothetical fix and one after. Keep the guidance comments in the box while you fill it in, they explain every rule.
       value: |
+        <!-- Two ordered lists, "Before a (hypothetical) fix" and "After a (hypothetical) fix", 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
+             Lead each list with one plain sentence saying where the flow fails (before) or would succeed (after), 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. "The upload hands back an ID that looks like OpenAI's own `file-abc123` instead of the scrambled one the gateway returned" is right, "no managed-file row was registered" is wrong
+             Keep the two lists step-for-step identical until they diverge, so the broken step is obvious
+             If the bug has a security or authorization consequence, end each list with what another user can or could no longer do
+
+        Example:
+
+        Before a (hypothetical) fix: a developer whose app streams chat completions gets no token counts back, so their cost dashboard reads zero
+
+        1. They send POST https://litellm-domain/v1/chat/completions with `"stream": true` and no `stream_options`
+        2. The last SSE chunk arrives with `"usage": null`, so their app records 0 prompt and 0 completion tokens
+        3. They open https://litellm-domain/ui/?page=logs and see the request logged at $0 spend
+
+        After a (hypothetical) fix: the same request comes back with real token counts, so the dashboard shows real spend
+
+        1. The proxy admin sets `always_include_stream_usage: true` and restarts the proxy
+        2. The developer sends the same POST https://litellm-domain/v1/chat/completions with `"stream": true` and no `stream_options`
+        3. The last SSE chunk now carries a `usage` object with real prompt and completion token counts
+        4. https://litellm-domain/ui/?page=logs shows that request at non-zero spend
+        -->
+
+        Before a (hypothetical) fix: 
+
+        1. 
+        2. 
+        3. 
+
+        After a (hypothetical) fix: 
+
         1. 
         2. 
         3. 
     validations:
       required: true
   - type: textarea
-    id: logs
+    id: proof-of-bug
     attributes:
-      label: Relevant log output
-      description: Please copy and paste any relevant log output. This will be automatically formatted into code, so no need for backticks.
-      render: shell
+      label: Proof the bug occurs
+      description: Paste the commands you ran and their output, captured against a live proxy with no mocks. Keep the guidance comments in the box while you fill it in, they explain every rule.
+      value: |
+        <!-- Include the commands (e.g., curl) and their full output, screenshots, or a screen recording demonstrating that the bug happens
+             The proof must be completely e2e with no mocks, against a live proxy you ran yourself (e.g., litellm --config config.yaml --detailed_debug on localhost:4000), hitting real LLM provider APIs and costing real $ where the bug involves a provider call. `pytest` commands are not enough
+             Show exactly what the end user sees or does, matching the User Flow above step for step
+             Include the LiteLLM version or commit hash the proof was captured at
+             If the bug applies to more than one of the LLM endpoints (/v1/responses, /v1/chat/completions, /v1/messages), include proof for every one of them, not just one
+             For UI bugs: include screenshots and the page URLs you were on
+             Redact API keys and any other secrets before pasting -->
+
+    validations:
+      required: true
   - type: dropdown
     id: component
     attributes:

CLAUDE.md

@@ -31,6 +31,8 @@ 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
 
+The same goes for filing a bug report: treat the comments and imperative instructions inside @.github/ISSUE_TEMPLATE/bug_report.yml as rules to follow, not just layout, and read that file from disk before writing an issue body so no stripped HTML comment escapes you
+
 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
 
 Never use `pytest` commands or the like as "Screenshots / Proof of Fix". We prefer curl'ing a live proxy instance running on localhost:4000 (I like to run it with `python litellm/proxy/proxy_cli.py --config litellm/proxy/dev_config.yaml --detailed_debug --reload --use_v2_migration_resolver 2>&1 | tee litellm.log`; the Admin UI dev server is `npm run dev` in `ui/litellm-dashboard`, served on port 3000) and showing both the command run and the output. Also, it should hit real LLM provider APIs, not mocks, and cost real $$$ because that is the most realistic test. The proof of fix should be exactly what the end user / customer would see / do. The run logs in PR #27703 is a prime example of how to do it (not a huge fan of using a python test script that future me and the team will have no visibility into; I prefer just curl commands or a short list of bash commands (e.g., using `for`)). If it's a UI thing, just tell me which URLs to go to (e.g., http://localhost:4000/ui/?page=logs), where to click, what fields to fill out, etc. along with the other commands to run in an ordered list, and I'll do it myself and post the screenshots after you make the PR