ADR-0016: Daily Reflection Cardinality — One DailyReflection per Day Key

Context

• Roadmap open question: One reflection per day rule.
• The UI intends Daily Reflection to be lightweight and repeatable (design principles).
• We will later generate weekly advice using an LLM; weekly packaging benefits from a consistent “one record per day” contract.
• However, users may:
  • Start a reflection, quit, and return later
  • Want multiple reflective notes on the same day
  • Miss days and backfill later

Constraints:

• Local-first; must behave well offline and across app restarts.

Decision

We will enforce at most one DailyReflection per day_key.

• Opening the Daily Reflection screen for a day:
  • If a reflection exists for the day key, open it.
  • Otherwise create a new DRAFT reflection for that day key.
• A reflection may be completed in multiple sessions.
• Multiple reflective thoughts in a day are supported via ProcessedItems of type Reflection (from processing flow), not by multiple DailyReflections.

We will represent reflection lifecycle with a status:

• DRAFT: in-progress, can be partial.
• SUBMITTED: user considers it done for the day, but may still edit later (edits update updated_at).

Scope boundaries:

• This ADR does not define locking rules (e.g., “no edits after submit”); by default edits remain allowed.

Rationale

• LLM packaging stability: A consistent “one reflection per day” structure makes weekly prompts simpler and reduces duplication.
• Reduces choice overload: Users don’t need to decide which “entry number” they’re on.
• Supports interruption: DRAFT status allows safe partial completion without creating multiple competing records.
• Separates journaling from daily ritual: Ad-hoc reflective notes can be captured as ProcessedItem(Reflection) through the normal processing flow.

Consequences

Positive effects:

• Simple uniqueness rule and predictable UI behavior.
• Weekly synthesis can assume a maximum of 7 daily reflections per week window.
• Allows backfilling: user can open a prior day and complete that day’s reflection.

Known downsides:

• Users who want multiple “full reflections” per day must either overwrite/edit the same entry or use multiple ProcessedItem reflections.
• If a user travels and their day boundary changes, day_key semantics must be clear (handled by ADR-0017).

Follow-up work:

• Decide whether SUBMITTED reflections are editable by default or require an “Edit” action.
• Define how ad-hoc ProcessedItem reflections surface in weekly synthesis (likely included, but distinct from DailyReflection).

Alternatives Considered

• Allow unlimited daily reflections — rejected: complicates UI and weekly packaging; creates selection ambiguity (“which entry represents the day?”).
• Force exactly one and disallow partial — rejected: increases friction; violates “lightweight and repeatable”.
• Auto-merge multiple reflections into one — rejected: introduces hidden behavior and unpredictability.

Notes

• This ADR intentionally biases toward predictable week-level aggregation, since weekly advice is a planned feature.