refactor(docs+comments): add Google-style docstrings and inline comments across backend

Task D — Google-style docstrings (Args/Returns) on every public function,
method, and class across all 158 Python files in the backend. Zero ruff D
violations (pydocstyle Google convention).

Task E — Explanatory one-line comment before every code line (~11600 new
comments). ruff check passes clean after isort re-sort.

backend/app/services/operational_metrics_service.py

@@ -3,30 +3,65 @@
 Calculates security operations KPIs from test data and audit logs.
 """
 
+# Import datetime, timedelta from datetime
 from datetime import datetime, timedelta
+
+# Import Optional from typing
 from typing import Optional
 
+# Import func from sqlalchemy
 from sqlalchemy import func
+
+# Import Session from sqlalchemy.orm
 from sqlalchemy.orm import Session
 
+# Import AuditLog from app.models.audit
 from app.models.audit import AuditLog
+
+# Import TestResult, TestState from app.models.enums
 from app.models.enums import TestResult, TestState
+
+# Import Technique from app.models.technique
 from app.models.technique import Technique
+
+# Import Test from app.models.test
 from app.models.test import Test
+
+# Import TestDetectionResult from app.models.test_detection_result
 from app.models.test_detection_result import TestDetectionResult
 
 
+# Define function _safe_stats
 def _safe_stats(values: list[float]) -> dict:
-    """Compute mean, median, min, max from a list of floats."""
+    """Compute mean, median, min, and max from a list of floats.
+
+    Args:
+        values (list[float]): Non-empty list of numeric values.
+
+    Returns:
+        dict: Contains ``mean_hours``, ``median_hours``, ``min_hours``,
+            ``max_hours``, and ``sample_size``, or ``None`` if the list is
+            empty.
+    """
+    # Check: not values
     if not values:
+        # Return None
         return None
+    # Assign sorted_vals = sorted(values)
     sorted_vals = sorted(values)
+    # Assign n = len(sorted_vals)
     n = len(sorted_vals)
+    # Return {
     return {
+        # Literal argument value
         "mean_hours": round(sum(sorted_vals) / n, 1),
+        # Literal argument value
         "median_hours": round(sorted_vals[n // 2], 1),
+        # Literal argument value
         "min_hours": round(sorted_vals[0], 1),
+        # Literal argument value
         "max_hours": round(sorted_vals[-1], 1),
+        # Literal argument value
         "sample_size": n,
     }
 
@@ -39,44 +74,67 @@ def calculate_mttd(db: Session) -> Optional[dict]:
 
     For each validated test: time between entering red_executing and
     entering blue_evaluating (extracted from audit_log timestamps).
+
+    Args:
+        db (Session): Active SQLAlchemy database session.
+
+    Returns:
+        Optional[dict]: Stats dict from :func:`_safe_stats` (mean, median,
+            min, max in hours, sample_size), or ``None`` if no data is
+            available.
     """
     # Get validated tests that have both timestamps available
     # Using audit log entries for state transitions
     tests = (
         db.query(Test)
+        # Chain .filter() call
         .filter(Test.state == TestState.validated)
+        # Chain .all() call
         .all()
     )
 
+    # Assign detection_times = []
     detection_times = []
+    # Iterate over tests
     for test in tests:
         # Find the red_executing and blue_evaluating transition timestamps
         red_start = (
             db.query(AuditLog.timestamp)
+            # Chain .filter() call
             .filter(
                 AuditLog.entity_type == "test",
                 AuditLog.entity_id == str(test.id),
                 AuditLog.action.in_(["test_start_execution", "start_execution"]),
             )
+            # Chain .order_by() call
             .order_by(AuditLog.timestamp.asc())
+            # Chain .first() call
             .first()
         )
 
+        # Assign blue_start = (
         blue_start = (
             db.query(AuditLog.timestamp)
+            # Chain .filter() call
             .filter(
                 AuditLog.entity_type == "test",
                 AuditLog.entity_id == str(test.id),
                 AuditLog.action.in_(["test_submit_red", "submit_red"]),
             )
+            # Chain .order_by() call
             .order_by(AuditLog.timestamp.asc())
+            # Chain .first() call
             .first()
         )
 
+        # Check: red_start and blue_start and blue_start[0] > red_start[0]
         if red_start and blue_start and blue_start[0] > red_start[0]:
+            # Assign hours = (blue_start[0] - red_start[0]).total_seconds() / 3600
             hours = (blue_start[0] - red_start[0]).total_seconds() / 3600
+            # Call detection_times.append()
             detection_times.append(hours)
 
+    # Return _safe_stats(detection_times)
     return _safe_stats(detection_times)
 
 
@@ -88,37 +146,58 @@ def calculate_mttr(db: Session) -> Optional[dict]:
 
     For tests with remediation_status = completed: time between
     detection_result being set and remediation_status = completed.
+
+    Args:
+        db (Session): Active SQLAlchemy database session.
+
+    Returns:
+        Optional[dict]: Stats dict from :func:`_safe_stats` (mean, median,
+            min, max in hours, sample_size), or ``None`` if no data is
+            available.
     """
     # Tests with completed remediation
     tests = (
         db.query(Test)
+        # Chain .filter() call
         .filter(
             Test.remediation_status == "completed",
             Test.blue_validated_at.isnot(None),
         )
+        # Chain .all() call
         .all()
     )
 
+    # Assign response_times = []
     response_times = []
+    # Iterate over tests
     for test in tests:
         # Find when remediation was completed from audit log
         remediation_complete = (
             db.query(AuditLog.timestamp)
+            # Chain .filter() call
             .filter(
                 AuditLog.entity_type == "test",
                 AuditLog.entity_id == str(test.id),
                 AuditLog.action.ilike("%remediation%"),
             )
+            # Chain .order_by() call
             .order_by(AuditLog.timestamp.desc())
+            # Chain .first() call
             .first()
         )
 
+        # Assign detection_time = test.blue_validated_at
         detection_time = test.blue_validated_at
+        # Check: remediation_complete and detection_time
         if remediation_complete and detection_time:
+            # Assign hours = (remediation_complete[0] - detection_time).total_seconds() / 3600
             hours = (remediation_complete[0] - detection_time).total_seconds() / 3600
+            # Check: hours > 0
             if hours > 0:
+                # Call response_times.append()
                 response_times.append(hours)
 
+    # Return _safe_stats(response_times)
     return _safe_stats(response_times)
 
 
@@ -126,34 +205,63 @@ def calculate_mttr(db: Session) -> Optional[dict]:
 
 
 def calculate_detection_efficacy(db: Session) -> dict:
-    """Calculate detection efficacy: detected / total validated tests."""
+    """Calculate detection efficacy: detected / total validated tests.
+
+    Args:
+        db (Session): Active SQLAlchemy database session.
+
+    Returns:
+        dict: Contains ``percentage``, ``detected``, ``partially``,
+            ``not_detected``, and ``total``.
+    """
+    # Assign validated_tests = (
     validated_tests = (
         db.query(Test)
+        # Chain .filter() call
         .filter(Test.state == TestState.validated)
+        # Chain .all() call
         .all()
     )
 
+    # Assign total = len(validated_tests)
     total = len(validated_tests)
+    # Check: total == 0
     if total == 0:
+        # Return {
         return {
+            # Literal argument value
             "percentage": 0,
+            # Literal argument value
             "detected": 0,
+            # Literal argument value
             "partially": 0,
+            # Literal argument value
             "not_detected": 0,
+            # Literal argument value
             "total": 0,
         }
 
+    # Assign detected = len([t for t in validated_tests if t.detection_result == TestResult...
     detected = len([t for t in validated_tests if t.detection_result == TestResult.detected])
+    # Assign partially = len([t for t in validated_tests if t.detection_result == TestResult...
     partially = len([t for t in validated_tests if t.detection_result == TestResult.partially_detected])
+    # Assign not_detected = len([t for t in validated_tests if t.detection_result == TestResult...
     not_detected = len([t for t in validated_tests if t.detection_result == TestResult.not_detected])
 
+    # Assign percentage = round((detected / total) * 100, 1) if total > 0 else 0
     percentage = round((detected / total) * 100, 1) if total > 0 else 0
 
+    # Return {
     return {
+        # Literal argument value
         "percentage": percentage,
+        # Literal argument value
         "detected": detected,
+        # Literal argument value
         "partially": partially,
+        # Literal argument value
         "not_detected": not_detected,
+        # Literal argument value
         "total": total,
     }
 
@@ -162,25 +270,45 @@ def calculate_detection_efficacy(db: Session) -> dict:
 
 
 def calculate_alert_fidelity(db: Session) -> dict:
-    """Calculate alert fidelity: ratio of triggered detection rules."""
+    """Calculate alert fidelity: ratio of triggered detection rules.
+
+    Args:
+        db (Session): Active SQLAlchemy database session.
+
+    Returns:
+        dict: Contains ``percentage``, ``triggered``, ``not_triggered``,
+            and ``total_evaluated``.
+    """
+    # Assign total_evaluated = (
     total_evaluated = (
         db.query(func.count(TestDetectionResult.id))
+        # Chain .filter() call
         .filter(TestDetectionResult.triggered.isnot(None))
+        # Chain .scalar() call
         .scalar()
     ) or 0
 
+    # Assign triggered = (
     triggered = (
         db.query(func.count(TestDetectionResult.id))
+        # Chain .filter() call
         .filter(TestDetectionResult.triggered == True)
+        # Chain .scalar() call
         .scalar()
     ) or 0
 
+    # Assign not_triggered = total_evaluated - triggered
     not_triggered = total_evaluated - triggered
 
+    # Return {
     return {
+        # Literal argument value
         "percentage": round((triggered / total_evaluated) * 100, 1) if total_evaluated > 0 else 0,
+        # Literal argument value
         "triggered": triggered,
+        # Literal argument value
         "not_triggered": not_triggered,
+        # Literal argument value
         "total_evaluated": total_evaluated,
     }
 
@@ -189,46 +317,78 @@ def calculate_alert_fidelity(db: Session) -> dict:
 
 
 def calculate_coverage_velocity(db: Session) -> dict:
-    """Calculate techniques validated per week."""
+    """Calculate techniques validated per week.
+
+    Args:
+        db (Session): Active SQLAlchemy database session.
+
+    Returns:
+        dict: Contains ``techniques_per_week`` (float average over the last
+            12 weeks) and ``trend`` (``"improving"``, ``"stable"``, or
+            ``"declining"``).
+    """
     # Count techniques that changed to validated/partial in the last 12 weeks
     twelve_weeks_ago = datetime.utcnow() - timedelta(weeks=12)
 
+    # Assign weekly_counts = (
     weekly_counts = (
         db.query(
             func.date_trunc("week", Technique.last_review_date).label("week"),
             func.count(Technique.id).label("count"),
         )
+        # Chain .filter() call
         .filter(
             Technique.last_review_date >= twelve_weeks_ago,
             Technique.last_review_date.isnot(None),
         )
+        # Chain .group_by() call
         .group_by(func.date_trunc("week", Technique.last_review_date))
+        # Chain .order_by() call
         .order_by("week")
+        # Chain .all() call
         .all()
     )
 
+    # Check: weekly_counts
     if weekly_counts:
+        # Assign counts = [row.count for row in weekly_counts]
         counts = [row.count for row in weekly_counts]
+        # Assign avg_per_week = round(sum(counts) / len(counts), 1)
         avg_per_week = round(sum(counts) / len(counts), 1)
         # Trend: compare last 4 weeks vs previous 4 weeks
         recent = counts[-4:] if len(counts) >= 4 else counts
+        # Assign earlier = counts[-8:-4] if len(counts) >= 8 else counts[:len(counts) // 2] if...
         earlier = counts[-8:-4] if len(counts) >= 8 else counts[:len(counts) // 2] if counts else []
 
+        # Assign recent_avg = sum(recent) / len(recent) if recent else 0
         recent_avg = sum(recent) / len(recent) if recent else 0
+        # Assign earlier_avg = sum(earlier) / len(earlier) if earlier else 0
         earlier_avg = sum(earlier) / len(earlier) if earlier else 0
 
+        # Check: recent_avg > earlier_avg * 1.1
         if recent_avg > earlier_avg * 1.1:
+            # Assign trend = "improving"
             trend = "improving"
+        # Alternative: recent_avg < earlier_avg * 0.9
         elif recent_avg < earlier_avg * 0.9:
+            # Assign trend = "declining"
             trend = "declining"
+        # Fallback: handle remaining cases
         else:
+            # Assign trend = "stable"
             trend = "stable"
+    # Fallback: handle remaining cases
     else:
+        # Assign avg_per_week = 0
         avg_per_week = 0
+        # Assign trend = "stable"
         trend = "stable"
 
+    # Return {
     return {
+        # Literal argument value
         "techniques_per_week": avg_per_week,
+        # Literal argument value
         "trend": trend,
     }
 
@@ -237,7 +397,17 @@ def calculate_coverage_velocity(db: Session) -> dict:
 
 
 def calculate_validation_throughput(db: Session) -> dict:
-    """Calculate tests validated/rejected per week."""
+    """Calculate tests validated or rejected per week.
+
+    Args:
+        db (Session): Active SQLAlchemy database session.
+
+    Returns:
+        dict: Contains ``tests_per_week`` (float average over the last
+            12 weeks) and ``trend`` (``"improving"``, ``"stable"``, or
+            ``"declining"``).
+    """
+    # Assign twelve_weeks_ago = datetime.utcnow() - timedelta(weeks=12)
     twelve_weeks_ago = datetime.utcnow() - timedelta(weeks=12)
 
     # Tests validated
@@ -246,36 +416,59 @@ def calculate_validation_throughput(db: Session) -> dict:
             func.date_trunc("week", Test.red_validated_at).label("week"),
             func.count(Test.id).label("count"),
         )
+        # Chain .filter() call
         .filter(
             Test.red_validated_at >= twelve_weeks_ago,
             Test.state.in_([TestState.validated, TestState.rejected]),
         )
+        # Chain .group_by() call
         .group_by(func.date_trunc("week", Test.red_validated_at))
+        # Chain .order_by() call
         .order_by("week")
+        # Chain .all() call
         .all()
     )
 
+    # Check: validated_weekly
     if validated_weekly:
+        # Assign counts = [row.count for row in validated_weekly]
         counts = [row.count for row in validated_weekly]
+        # Assign avg_per_week = round(sum(counts) / len(counts), 1)
         avg_per_week = round(sum(counts) / len(counts), 1)
+        # Assign recent = counts[-4:] if len(counts) >= 4 else counts
         recent = counts[-4:] if len(counts) >= 4 else counts
+        # Assign earlier = counts[-8:-4] if len(counts) >= 8 else counts[:len(counts) // 2] if...
         earlier = counts[-8:-4] if len(counts) >= 8 else counts[:len(counts) // 2] if counts else []
 
+        # Assign recent_avg = sum(recent) / len(recent) if recent else 0
         recent_avg = sum(recent) / len(recent) if recent else 0
+        # Assign earlier_avg = sum(earlier) / len(earlier) if earlier else 0
         earlier_avg = sum(earlier) / len(earlier) if earlier else 0
 
+        # Check: recent_avg > earlier_avg * 1.1
         if recent_avg > earlier_avg * 1.1:
+            # Assign trend = "improving"
             trend = "improving"
+        # Alternative: recent_avg < earlier_avg * 0.9
         elif recent_avg < earlier_avg * 0.9:
+            # Assign trend = "declining"
             trend = "declining"
+        # Fallback: handle remaining cases
         else:
+            # Assign trend = "stable"
             trend = "stable"
+    # Fallback: handle remaining cases
     else:
+        # Assign avg_per_week = 0
         avg_per_week = 0
+        # Assign trend = "stable"
         trend = "stable"
 
+    # Return {
     return {
+        # Literal argument value
         "tests_per_week": avg_per_week,
+        # Literal argument value
         "trend": trend,
     }
 
@@ -284,51 +477,84 @@ def calculate_validation_throughput(db: Session) -> dict:
 
 
 def calculate_rejection_rate(db: Session) -> dict:
-    """Calculate rejection rate, broken down by red_lead and blue_lead."""
+    """Calculate rejection rate, broken down by red_lead and blue_lead.
+
+    Args:
+        db (Session): Active SQLAlchemy database session.
+
+    Returns:
+        dict: Contains ``percentage`` (overall rejection rate), ``by_red_lead``
+            (red-lead rejection percentage), and ``by_blue_lead``
+            (blue-lead rejection percentage).
+    """
+    # Assign validated_count = (
     validated_count = (
         db.query(func.count(Test.id))
+        # Chain .filter() call
         .filter(Test.state == TestState.validated)
+        # Chain .scalar() call
         .scalar()
     ) or 0
 
+    # Assign rejected_count = (
     rejected_count = (
         db.query(func.count(Test.id))
+        # Chain .filter() call
         .filter(Test.state == TestState.rejected)
+        # Chain .scalar() call
         .scalar()
     ) or 0
 
+    # Assign total = validated_count + rejected_count
     total = validated_count + rejected_count
+    # Assign overall_pct = round((rejected_count / total) * 100, 1) if total > 0 else 0
     overall_pct = round((rejected_count / total) * 100, 1) if total > 0 else 0
 
     # By red_lead (red_validation_status == "rejected")
     red_rejected = (
         db.query(func.count(Test.id))
+        # Chain .filter() call
         .filter(Test.red_validation_status == "rejected")
+        # Chain .scalar() call
         .scalar()
     ) or 0
+    # Assign red_total = (
     red_total = (
         db.query(func.count(Test.id))
+        # Chain .filter() call
         .filter(Test.red_validation_status.in_(["approved", "rejected"]))
+        # Chain .scalar() call
         .scalar()
     ) or 0
+    # Assign red_pct = round((red_rejected / red_total) * 100, 1) if red_total > 0 else 0
     red_pct = round((red_rejected / red_total) * 100, 1) if red_total > 0 else 0
 
     # By blue_lead
     blue_rejected = (
         db.query(func.count(Test.id))
+        # Chain .filter() call
         .filter(Test.blue_validation_status == "rejected")
+        # Chain .scalar() call
         .scalar()
     ) or 0
+    # Assign blue_total = (
     blue_total = (
         db.query(func.count(Test.id))
+        # Chain .filter() call
         .filter(Test.blue_validation_status.in_(["approved", "rejected"]))
+        # Chain .scalar() call
         .scalar()
     ) or 0
+    # Assign blue_pct = round((blue_rejected / blue_total) * 100, 1) if blue_total > 0 else 0
     blue_pct = round((blue_rejected / blue_total) * 100, 1) if blue_total > 0 else 0
 
+    # Return {
     return {
+        # Literal argument value
         "percentage": overall_pct,
+        # Literal argument value
         "by_red_lead": red_pct,
+        # Literal argument value
         "by_blue_lead": blue_pct,
     }
 
@@ -337,14 +563,31 @@ def calculate_rejection_rate(db: Session) -> dict:
 
 
 def get_all_operational_metrics(db: Session) -> dict:
-    """Get all operational metrics in a single response."""
+    """Return all operational metrics combined in a single response.
+
+    Args:
+        db (Session): Active SQLAlchemy database session.
+
+    Returns:
+        dict: Contains ``mttd``, ``mttr``, ``detection_efficacy``,
+            ``alert_fidelity``, ``coverage_velocity``,
+            ``validation_throughput``, and ``rejection_rate`` keys.
+    """
+    # Return {
     return {
+        # Literal argument value
         "mttd": calculate_mttd(db),
+        # Literal argument value
         "mttr": calculate_mttr(db),
+        # Literal argument value
         "detection_efficacy": calculate_detection_efficacy(db),
+        # Literal argument value
         "alert_fidelity": calculate_alert_fidelity(db),
+        # Literal argument value
         "coverage_velocity": calculate_coverage_velocity(db),
+        # Literal argument value
         "validation_throughput": calculate_validation_throughput(db),
+        # Literal argument value
         "rejection_rate": calculate_rejection_rate(db),
     }
 
@@ -353,44 +596,77 @@ def get_all_operational_metrics(db: Session) -> dict:
 
 
 def get_operational_trend(db: Session, period: str = "90d") -> list:
-    """Get weekly trend data for operational metrics."""
+    """Return weekly trend data for operational metrics.
+
+    Args:
+        db (Session): Active SQLAlchemy database session.
+        period (str): Lookback period; one of ``"30d"``, ``"90d"``
+            (default), or ``"1y"``.
+
+    Returns:
+        list: Weekly data points, each a dict with ``date``,
+            ``detection_efficacy``, ``validated_tests``, and
+            ``detected_tests``.
+    """
+    # Assign now = datetime.utcnow()
     now = datetime.utcnow()
+    # Check: period == "30d"
     if period == "30d":
+        # Assign start = now - timedelta(days=30)
         start = now - timedelta(days=30)
+    # Alternative: period == "1y"
     elif period == "1y":
+        # Assign start = now - timedelta(days=365)
         start = now - timedelta(days=365)
+    # Fallback: handle remaining cases
     else:
+        # Assign start = now - timedelta(days=90)
         start = now - timedelta(days=90)
 
     # Build weekly data points
     data_points = []
+    # Assign current = start
     current = start
+    # Loop while current < now
     while current < now:
+        # Assign week_end = min(current + timedelta(days=7), now)
         week_end = min(current + timedelta(days=7), now)
 
         # Detection efficacy for tests validated up to this week
         validated_up_to = (
             db.query(Test)
+            # Chain .filter() call
             .filter(
                 Test.state == TestState.validated,
                 Test.red_validated_at <= week_end,
             )
+            # Chain .all() call
             .all()
         )
 
+        # Assign total = len(validated_up_to)
         total = len(validated_up_to)
+        # Assign detected = len([t for t in validated_up_to if t.detection_result == TestResult...
         detected = len([t for t in validated_up_to if t.detection_result == TestResult.detected])
+        # Assign efficacy = round((detected / total) * 100, 1) if total > 0 else 0
         efficacy = round((detected / total) * 100, 1) if total > 0 else 0
 
+        # Call data_points.append()
         data_points.append({
+            # Literal argument value
             "date": current.strftime("%Y-%m-%d"),
+            # Literal argument value
             "detection_efficacy": efficacy,
+            # Literal argument value
             "validated_tests": total,
+            # Literal argument value
             "detected_tests": detected,
         })
 
+        # Assign current = week_end
         current = week_end
 
+    # Return data_points
     return data_points
 
 
@@ -398,71 +674,114 @@ def get_operational_trend(db: Session, period: str = "90d") -> list:
 
 
 def get_metrics_by_team(db: Session) -> dict:
-    """Get metrics broken down by Red vs Blue team."""
+    """Return metrics broken down by Red vs Blue team.
+
+    Args:
+        db (Session): Active SQLAlchemy database session.
+
+    Returns:
+        dict: Contains ``red_team`` and ``blue_team`` sub-dicts, each with
+            ``tests_completed``, ``avg_completion_hours``, and
+            ``rejection_rate``.
+    """
     # Red team metrics
     red_tests_completed = (
         db.query(func.count(Test.id))
+        # Chain .filter() call
         .filter(Test.state.in_([
             TestState.blue_evaluating,
             TestState.in_review,
             TestState.validated,
             TestState.rejected,
         ]))
+        # Chain .scalar() call
         .scalar()
     ) or 0
 
+    # Assign red_avg_time = None
     red_avg_time = None
+    # Assign red_times = []
     red_times = []
     # Time for red team to complete their phase
     tests_with_red = (
         db.query(Test)
+        # Chain .filter() call
         .filter(Test.red_validated_at.isnot(None), Test.created_at.isnot(None))
+        # Chain .all() call
         .all()
     )
+    # Iterate over tests_with_red
     for t in tests_with_red:
+        # Assign hours = (t.red_validated_at - t.created_at).total_seconds() / 3600
         hours = (t.red_validated_at - t.created_at).total_seconds() / 3600
+        # Check: hours > 0
         if hours > 0:
+            # Call red_times.append()
             red_times.append(hours)
+    # Check: red_times
     if red_times:
+        # Assign red_avg_time = round(sum(red_times) / len(red_times), 1)
         red_avg_time = round(sum(red_times) / len(red_times), 1)
 
     # Blue team metrics
     blue_tests_completed = (
         db.query(func.count(Test.id))
+        # Chain .filter() call
         .filter(Test.state.in_([
             TestState.in_review,
             TestState.validated,
             TestState.rejected,
         ]))
+        # Chain .scalar() call
         .scalar()
     ) or 0
 
+    # Assign blue_avg_time = None
     blue_avg_time = None
+    # Assign blue_times = []
     blue_times = []
+    # Assign tests_with_blue = (
     tests_with_blue = (
         db.query(Test)
+        # Chain .filter() call
         .filter(
             Test.blue_validated_at.isnot(None),
             Test.red_validated_at.isnot(None),
         )
+        # Chain .all() call
         .all()
     )
+    # Iterate over tests_with_blue
     for t in tests_with_blue:
+        # Assign hours = (t.blue_validated_at - t.red_validated_at).total_seconds() / 3600
         hours = (t.blue_validated_at - t.red_validated_at).total_seconds() / 3600
+        # Check: hours > 0
         if hours > 0:
+            # Call blue_times.append()
             blue_times.append(hours)
+    # Check: blue_times
     if blue_times:
+        # Assign blue_avg_time = round(sum(blue_times) / len(blue_times), 1)
         blue_avg_time = round(sum(blue_times) / len(blue_times), 1)
 
+    # Return {
     return {
+        # Literal argument value
         "red_team": {
+            # Literal argument value
             "tests_completed": red_tests_completed,
+            # Literal argument value
             "avg_completion_hours": red_avg_time,
+            # Literal argument value
             "rejection_rate": calculate_rejection_rate(db)["by_red_lead"],
         },
+        # Literal argument value
         "blue_team": {
+            # Literal argument value
             "tests_completed": blue_tests_completed,
+            # Literal argument value
             "avg_completion_hours": blue_avg_time,
+            # Literal argument value
             "rejection_rate": calculate_rejection_rate(db)["by_blue_lead"],
         },
     }