From 5643a59aa4e0a7322a14ac0645dad21631cd66f8 Mon Sep 17 00:00:00 2001
From: mateo <mateo@berri.ai>
Date: Tue, 11 Aug 2026 02:58:21 +0000
Subject: [PATCH] fix: move bug report guidance out of prefilled values so
 required means filled

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 .github/ISSUE_TEMPLATE/bug_report.yml | 61 ++++++++++-----------------
 CLAUDE.md                             |  2 +-
 2 files changed, 23 insertions(+), 40 deletions(-)

diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml
index 86f66764ab0..7e08f9297f8 100644
--- a/.github/ISSUE_TEMPLATE/bug_report.yml
+++ b/.github/ISSUE_TEMPLATE/bug_report.yml
@@ -23,71 +23,54 @@ body:
       label: What happened?
       description: Also tell us, what did you expect to happen?
       placeholder: Tell us what you see!
-      value: "A bug happened!"
     validations:
       required: true
   - type: textarea
     id: user-flow
     attributes:
       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:
+      description: |
+        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. Every rule below applies.
 
+        - 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
+      placeholder: |
         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
+        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
+        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: proof-of-bug
     attributes:
       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
-             Start with the config.yaml (or SDK setup) and any env vars the proxy ran with, then the exact version or commit hash the proof was captured at, so a maintainer can stand up the same proxy before running your commands. Keep the real values for env vars that aren't sensitive, they are often the reason the bug happens, 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 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. Scrub keys and tokens out of screenshots too, they show up in headers, request panels, and the Admin UI -->
+      description: |
+        The commands (e.g., curl) and their full output, screenshots, or a screen recording demonstrating that the bug happens. Every rule below applies.
 
+        - 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
+        - Start with the config.yaml (or SDK setup) and any env vars the proxy ran with, then the exact version or commit hash the proof was captured at, so a maintainer can stand up the same proxy before running your commands. Keep the real values for env vars that aren't sensitive, they are often the reason the bug happens, 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 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. Scrub keys and tokens out of screenshots too, they show up in headers, request panels, and the Admin UI
+      placeholder: |
         Config / setup the proxy ran with:
 
         Version or commit:
 
         Commands and their full output:
-
     validations:
       required: true
   - type: checkboxes
diff --git a/CLAUDE.md b/CLAUDE.md
index e4f027715cc..3941060afa2 100644
--- a/CLAUDE.md
+++ b/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
 
-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
+The same goes for filing a bug report: treat every field's `description` and `placeholder` in @.github/ISSUE_TEMPLATE/bug_report.yml as rules to follow, not just layout, and read that file from disk before writing an issue body, since the rendered form and any copy injected into your context can drop or reflow that guidance
 
 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