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

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