ADR-0040: Weekly Synthesis Aggregation Window Definition

Context

Phase 8 introduces WeeklySynthesis — an LLM-generated record that aggregates a user's DailyReflection entries for a given week into structured insights. Before the user-triggered synthesis can run, the system must answer three questions:

1. What constitutes a "week" (its start and end boundaries)?
2. Which DailyReflection entries fall inside that window?
3. How many completed reflections are required before synthesis is considered meaningful, and from what point in the week is the user allowed to trigger it?

These rules must be deterministic and unambiguous so that the UI can correctly gate the trigger and store synthesis records against a stable key.

Decision

We will define a week as Monday 00:00 – Sunday 23:59 in the device's local timezone (ISO 8601 week starting on Monday), identified by its ISO week key (e.g. 2026-W09).

Minimum threshold: A WeeklySynthesis will only be produced for weeks that contain at least 3 completed DailyReflection entries. If fewer exist, the trigger is disabled in the UI and no synthesis row is created.

Trigger window: The user may trigger synthesis for week N starting from Saturday of week N onward (i.e. day 6 of the ISO week). This supports a "weekend review" model where the user reflects on the bulk of their week (Mon–Fri) before it formally closes on Sunday. Synthesis for a past week (week_key < current week) is triggerable at any time, subject to the minimum threshold.

Day membership: A DailyReflection belongs to the week that contains its day_key date (using the same Monday-anchored ISO week logic).

Week key format: WeeklySynthesis records are keyed by week_key in the form YYYY-Www (e.g. 2026-W09), consistent with the day_key strategy established in ADR-0017.

Rationale

• ISO Monday start is the global standard and aligns with how most productivity practitioners frame their weekly review. It avoids ambiguity for international users.
• 3-reflection minimum ensures that synthesis reflects meaningful longitudinal data rather than a near-empty week. A majority-of-weekdays heuristic (3 of 5) is practical without being so strict that occasional missed days block the feature entirely.
• Saturday trigger window matches natural productivity behaviour: the weekend is when users review their week. Allowing synthesis from Saturday means Mon–Fri reflections (3–5 entries) are already available before the week formally closes. Sunday is still included as a valid trigger day. Requiring the week to be fully closed before triggering would make the feature feel delayed and less useful.
• No partial synthesis keeps the data model clean. A WeeklySynthesis row either represents a complete-enough week or does not exist. This avoids explaining "incomplete" states in the UI.
• ISO YYYY-Www key mirrors the day_key pattern and is human-readable, unambiguous, and stable for storage as a primary key.

Consequences

• The ViewModel must derive week_key from LocalDate using WeekFields.ISO and evaluate whether LocalDate.now().dayOfWeek >= DayOfWeek.SATURDAY before enabling the trigger button.
• The DAO query to count eligible reflections filters by week_key and status = COMPLETED.
• The UI trigger button is disabled when: the reflection count for the target week is < 3, OR today is before Saturday of that week, OR a COMPLETED synthesis already exists for that week.
• UI must handle the absence of a WeeklySynthesis for a given week gracefully (no error state, simply "not yet available" or "Review available from Saturday").
• Timezone edge cases (DST transitions, manual timezone changes) are tolerated: day_key is determined at write time for each reflection (ADR-0017), so the week key derivation is stable.

Alternatives Considered

• Sunday–Saturday (US week) — rejected; ISO Monday-start is the more internationally neutral default and consistent with productivity literature.
• Rolling 7-day window — rejected; makes week_key ambiguous and prevents stable storage keying.
• No minimum / synthesize any week — rejected; a single-reflection synthesis would produce low-quality output and waste LLM resources.

Notes

• Related: ADR-0017 (timezone and day-key strategy)
• The week_key column on weekly_syntheses will reference the ISO week, not a foreign key to individual reflections.
• If a user's first week of use starts mid-week, that partial week is likely to have fewer than 3 reflections and will simply not produce a synthesis — no special handling needed.