docs: add summary docstrings to all python scripts explaining their purpose

scripts/backlog-analysis/analyze_bugs.py

@@ -1,3 +1,7 @@
+"""
+Purpose: Performs fast, static initial triage of issues.
+It sends the issue text along with a static representation of the directory tree to Gemini in a single turn. Useful for quick first-pass estimations without the overhead of deep codebase search.
+"""
 import json
 import urllib.request
 import urllib.error

scripts/backlog-analysis/bug_analyzer_final.py

@@ -1,3 +1,7 @@
+"""
+Purpose: Performs deep, agentic analysis on backlog issues.
+It equips the Gemini model with tool-calling capabilities (grep and file reading), allowing it to autonomously navigate the codebase and investigate the root cause over multiple turns (up to 30) for high-accuracy effort estimation.
+"""
 import json
 import urllib.request
 import urllib.error

scripts/backlog-analysis/generate_bugs_csv.py

@@ -1,3 +1,7 @@
+"""
+Purpose: Exports analyzed JSON issue data into a human-readable CSV format.
+This is typically the final step in the workflow, making the output suitable for sharing, spreadsheet import, or manual review.
+"""
 import json
 import csv
 from datetime import datetime

scripts/backlog-analysis/generic_processor.py

@@ -1,3 +1,7 @@
+"""
+Purpose: A highly configurable, generic agentic processor for any backlog task.
+Unlike the specific bug analyzers, this script accepts custom system prompts, input datasets, and output locations via command-line arguments, making it reusable for features, label updates, or custom queries.
+"""
 import json
 import urllib.request
 import os

scripts/backlog-analysis/single_turn_bug_analyzer.py

@@ -1,3 +1,7 @@
+"""
+Purpose: Performs a single-turn analysis on backlog issues.
+It pre-fetches context by grepping the codebase for keywords found in the issue description, then sends a single prompt to Gemini to determine the root cause and effort level. Faster than agentic analysis but more grounded than static analysis.
+"""
 import json
 import urllib.request
 import os

scripts/backlog-analysis/utils/debug_bug.py

@@ -1,3 +1,7 @@
+"""
+Purpose: A utility to execute the agentic analysis loop on a single, specific issue by its ID.
+Extremely useful for observing the tool-calling behavior, debugging prompts, or fixing edge cases without running the entire batch.
+"""
 import json
 import urllib.request
 import urllib.error

scripts/backlog-analysis/utils/generate_recommended_fixes.py

@@ -1,3 +1,7 @@
+"""
+Purpose: A focused script to generate or extract 'recommended_implementation' details for issues categorized as 'small' effort.
+Helps create actionable code snippets for easy wins.
+"""
 import json
 import urllib.request
 import os

scripts/backlog-analysis/utils/inject_manual_fixes.py

@@ -1,3 +1,7 @@
+"""
+Purpose: Injects recommended implementation snippets into the JSON data for specific, well-understood issues.
+Allows maintainers to supplement AI analysis with exact code fixes.
+"""
 import json
 
 BUGS_FILE = '../data/bugs.json'

scripts/backlog-analysis/utils/reclassify_effort.py

@@ -1,3 +1,7 @@
+"""
+Purpose: Re-evaluates and modifies the effort level of specific issues based on hardcoded lists or heuristics.
+Useful for bulk-updating effort levels (e.g., forcing certain complex bugs to 'large') after the initial AI pass.
+"""
 import json
 import re
 

scripts/backlog-analysis/utils/update_manual_bugs.py

@@ -1,3 +1,7 @@
+"""
+Purpose: Updates the primary JSON data file with manually provided analysis.
+Used to explicitly override or inject specific 'analysis', 'effort_level', and 'reasoning' values for known issues where AI analysis is insufficient.
+"""
 import json
 
 BUGS_FILE = '../data/bugs.json'

scripts/backlog-analysis/utils/update_verified_bugs.py

@@ -1,3 +1,7 @@
+"""
+Purpose: Marks specific issues in the JSON dataset as 'validated = true'.
+Used to track which AI analyses have been manually reviewed and approved by a human maintainer.
+"""
 import json
 
 BUGS_FILE = '../data/bugs.json'

scripts/backlog-analysis/utils/validate_effort.py

@@ -1,3 +1,7 @@
+"""
+Purpose: Runs heuristic post-analysis validation on the AI's effort estimations.
+Checks for keywords (like 'Windows', 'WSL', 'PTY') in the issue body to ensure the AI didn't underestimate platform-specific or architecturally complex bugs as 'small'.
+"""
 import json
 import re
 import os