From 268fe7cbe11f55b8508a837088a6b3000bba7f96 Mon Sep 17 00:00:00 2001
From: Coco Sheng <cocosheng@google.com>
Date: Wed, 6 May 2026 16:04:00 -0400
Subject: [PATCH] chore: organize auxiliary and validation scripts into a utils
 directory

---
 scripts/backlog-analysis/README.md                     | 10 +++++++---
 scripts/backlog-analysis/{ => utils}/debug_bug.py      |  4 ++--
 .../{ => utils}/generate_recommended_fixes.py          |  0
 .../{ => utils}/inject_manual_fixes.py                 |  2 +-
 .../backlog-analysis/{ => utils}/reclassify_effort.py  |  2 +-
 .../backlog-analysis/{ => utils}/update_manual_bugs.py |  2 +-
 .../{ => utils}/update_verified_bugs.py                |  2 +-
 .../backlog-analysis/{ => utils}/validate_effort.py    |  0
 8 files changed, 13 insertions(+), 9 deletions(-)
 rename scripts/backlog-analysis/{ => utils}/debug_bug.py (96%)
 rename scripts/backlog-analysis/{ => utils}/generate_recommended_fixes.py (100%)
 rename scripts/backlog-analysis/{ => utils}/inject_manual_fixes.py (98%)
 rename scripts/backlog-analysis/{ => utils}/reclassify_effort.py (99%)
 rename scripts/backlog-analysis/{ => utils}/update_manual_bugs.py (99%)
 rename scripts/backlog-analysis/{ => utils}/update_verified_bugs.py (99%)
 rename scripts/backlog-analysis/{ => utils}/validate_effort.py (100%)

diff --git a/scripts/backlog-analysis/README.md b/scripts/backlog-analysis/README.md
index 2ecdc3100a..8ce02e6631 100644
--- a/scripts/backlog-analysis/README.md
+++ b/scripts/backlog-analysis/README.md
@@ -7,7 +7,10 @@ and determining implementation effort levels for the Gemini CLI project.
 
 - `data/`: Contains the issue data in JSON and CSV formats.
   - `bugs.json`: The primary source of truth for bug analysis.
-- `*.py`: Analysis and utility scripts.
+- `utils/`: Auxiliary scripts for manual overrides, debugging, and post-analysis
+  validation (e.g., `validate_effort.py`, `inject_manual_fixes.py`).
+- `*.py`: Core analysis and export scripts (e.g., `bug_analyzer_final.py`,
+  `generate_bugs_csv.py`).
 - `loop_analyzer.sh`: A shell script for running iterative analysis until all
   issues are processed.
 
@@ -39,10 +42,11 @@ Runs the single-turn analyzer in a loop until all issues have a valid analysis.
 
 ### 4. Validation & Export
 
-Run these after analysis to ensure consistency and generate a readable report.
+Run validation from the utils folder to ensure consistency, then generate a
+readable report.
 
 ```bash
-python3 validate_effort.py
+python3 utils/validate_effort.py
 python3 generate_bugs_csv.py
 ```
 
diff --git a/scripts/backlog-analysis/debug_bug.py b/scripts/backlog-analysis/utils/debug_bug.py
similarity index 96%
rename from scripts/backlog-analysis/debug_bug.py
rename to scripts/backlog-analysis/utils/debug_bug.py
index 0e802cebf7..cfb00cb292 100644
--- a/scripts/backlog-analysis/debug_bug.py
+++ b/scripts/backlog-analysis/utils/debug_bug.py
@@ -52,7 +52,7 @@ def execute_tool(call):
         except: return "Error or no results."
     elif name == 'read_file':
         f = args.get('filepath', '')
-        if not f.startswith('/'): f = os.path.join('../../packages', f)
+        if not f.startswith('/'): f = os.path.join('../../../packages', f)
         if not os.path.exists(f): return "File not found."
         try:
             return subprocess.check_output(f'head -n 200 "{f}"', shell=True, text=True)
@@ -60,7 +60,7 @@ def execute_tool(call):
     return "Unknown tool"
 
 def debug_one(issue_num):
-    with open('data/bugs.json', 'r') as f:
+    with open('../data/bugs.json', 'r') as f:
         bugs = json.load(f)
     issue = next(b for b in bugs if b['number'] == issue_num)
     
diff --git a/scripts/backlog-analysis/generate_recommended_fixes.py b/scripts/backlog-analysis/utils/generate_recommended_fixes.py
similarity index 100%
rename from scripts/backlog-analysis/generate_recommended_fixes.py
rename to scripts/backlog-analysis/utils/generate_recommended_fixes.py
diff --git a/scripts/backlog-analysis/inject_manual_fixes.py b/scripts/backlog-analysis/utils/inject_manual_fixes.py
similarity index 98%
rename from scripts/backlog-analysis/inject_manual_fixes.py
rename to scripts/backlog-analysis/utils/inject_manual_fixes.py
index 995ac60bd2..38bef4cfd6 100644
--- a/scripts/backlog-analysis/inject_manual_fixes.py
+++ b/scripts/backlog-analysis/utils/inject_manual_fixes.py
@@ -1,6 +1,6 @@
 import json
 
-BUGS_FILE = 'data/bugs.json'
+BUGS_FILE = '../data/bugs.json'
 
 with open(BUGS_FILE, 'r') as f:
     bugs = json.load(f)
diff --git a/scripts/backlog-analysis/reclassify_effort.py b/scripts/backlog-analysis/utils/reclassify_effort.py
similarity index 99%
rename from scripts/backlog-analysis/reclassify_effort.py
rename to scripts/backlog-analysis/utils/reclassify_effort.py
index 8bce456d96..35ee7d1c71 100644
--- a/scripts/backlog-analysis/reclassify_effort.py
+++ b/scripts/backlog-analysis/utils/reclassify_effort.py
@@ -1,7 +1,7 @@
 import json
 import re
 
-BUGS_FILE = 'data/bugs.json'
+BUGS_FILE = '../data/bugs.json'
 
 with open(BUGS_FILE, 'r') as f:
     bugs = json.load(f)
diff --git a/scripts/backlog-analysis/update_manual_bugs.py b/scripts/backlog-analysis/utils/update_manual_bugs.py
similarity index 99%
rename from scripts/backlog-analysis/update_manual_bugs.py
rename to scripts/backlog-analysis/utils/update_manual_bugs.py
index 4f8c42c3aa..7a6fb5cd7b 100644
--- a/scripts/backlog-analysis/update_manual_bugs.py
+++ b/scripts/backlog-analysis/utils/update_manual_bugs.py
@@ -1,6 +1,6 @@
 import json
 
-BUGS_FILE = 'data/bugs.json'
+BUGS_FILE = '../data/bugs.json'
 
 with open(BUGS_FILE, 'r') as f:
     bugs = json.load(f)
diff --git a/scripts/backlog-analysis/update_verified_bugs.py b/scripts/backlog-analysis/utils/update_verified_bugs.py
similarity index 99%
rename from scripts/backlog-analysis/update_verified_bugs.py
rename to scripts/backlog-analysis/utils/update_verified_bugs.py
index 94f9cae6c7..83b78ab0af 100644
--- a/scripts/backlog-analysis/update_verified_bugs.py
+++ b/scripts/backlog-analysis/utils/update_verified_bugs.py
@@ -1,6 +1,6 @@
 import json
 
-BUGS_FILE = 'data/bugs.json'
+BUGS_FILE = '../data/bugs.json'
 
 with open(BUGS_FILE, 'r') as f:
     bugs = json.load(f)
diff --git a/scripts/backlog-analysis/validate_effort.py b/scripts/backlog-analysis/utils/validate_effort.py
similarity index 100%
rename from scripts/backlog-analysis/validate_effort.py
rename to scripts/backlog-analysis/utils/validate_effort.py