diff --git a/src/shared/shared/week_keys.py b/src/shared/shared/week_keys.py
index d546be2..e16cac6 100644
--- a/src/shared/shared/week_keys.py
+++ b/src/shared/shared/week_keys.py
@@ -24,6 +24,12 @@ def week_id_iso(dt: datetime) -> str:
 
 
 def candidate_week_ids(dt: datetime) -> tuple[str, ...]:
+    """Return U-week then ISO encodings of the same instant.
+
+    Dual-read does not advance the calendar week. ``%Y-W%U`` and ``%G-W%V``
+    are two strftime renderings of ``dt``. Example: 2026-01-01 encodes as
+    ("2026-W00", "2026-W01"), not as "this week" then "next week".
+    """
     u_week = week_id_ustrftime(dt)
     iso_week = week_id_iso(dt)
     if u_week == iso_week:
diff --git a/tests/test_week_keys.py b/tests/test_week_keys.py
index 1400f81..ed2bce9 100644
--- a/tests/test_week_keys.py
+++ b/tests/test_week_keys.py
@@ -24,6 +24,7 @@ def test_ustrftime_and_iso_differ_on_new_year():
 
 
 def test_candidate_week_ids_u_week_first_then_iso():
+    # 2026-01-01: same instant encoded two ways, not a next-week lookup.
     assert candidate_week_ids(MISMATCH_DT) == ("2026-W00", "2026-W01")