FEATURE SPEC¶

Questions or comments?

Post them as a comment on the tracking issue -- requires a GitHub account with access to this repo.

Notifications and Async Activity Signals¶

Novaworks AI | CTO Office | Q3 2026 | DRAFT

Parent PRD: ../concept.md, Section 2. Status: TBD — open questions below are unresolved; this spec should not move to implementation until they are answered.

History¶

Version	Date	Author / Notes
1	July 28, 2026	Eswar Vandanapu — Initial draft, derived from PRD Section 2.

Problem Statement¶

Employees interacting with Novaworks through third-party host surfaces (Gemini Workspace and others) have no way to learn about unread notifications, overdue tasks, or pending approvals unless they happen to check the Nova portal directly. Because these host surfaces are reactive chat interfaces — they only respond when a user initiates a conversation — Novaworks cannot proactively push anything to the user. The only moment available to surface this information is when the user starts a chat.

Objective¶

When a user initiates a chat on any supported host surface, and that user has expired/unread notifications or overdue tasks, nudge them within the chat response to make them aware, with a deep link to the Nova portal where they can view and act on the underlying items.

Scope¶

In Scope¶

Detecting, at the start of a chat interaction, whether the initiating user has unread notifications or overdue tasks
Injecting a nudge into the agent's response indicating the presence of such items
Including a deep link to the Nova portal interface where the user can view and act on them

Out of Scope¶

Native push notifications, Slack/Teams messages, mobile push, email digests, or any other proactive delivery channel. This spec covers only the in-chat nudge triggered by the user initiating a conversation.
Any mechanism that proactively contacts the user outside of a chat session they initiated. Host chat surfaces are reactive by design; this is a platform constraint, not a phased rollout — no native-notification integration is planned for these surfaces.

Functional Behavior¶

User initiates a chat on a host surface (e.g., Gemini Workspace).
Before or alongside generating the primary response, the Gateway/proxy layer checks whether the user has:
Unread notifications
Expired notifications
Overdue tasks
If any are present, the agent response includes a nudge segment informing the user, plus a deep link to the Nova portal.
If none are present, no nudge is added — the response is unaffected.

Compatibility¶

Per the PRD's compatibility matrix (row: "Notifications and async signals"): Portal is Full, A2A and MCP are TBD. The general fallback pattern for this capability is: notify pending actions in a chat with a deeplink as a fallback when richer rendering isn't available on a given transport.

Resolved Decisions¶

Content specificity (was Open Question 1): The nudge lists items individually when the user has fewer than 3 pending items (notifications + overdue tasks combined); at 3 or more, it collapses to a count (e.g., "You have 4 overdue tasks and 1 pending notification — click the link to review.").

Rationale: general UX research on notification design pulls in two directions — specificity/actionability improves engagement, while chatbot-specific guidance warns against letting a proactive nudge overwhelm an unrelated conversation. A count-based cutoff gets the actionability benefit for the common case (most users likely have 1-2 items) while avoiding a wall of text for users with a backlog, deferring full detail to the portal deep link. This is based on general industry research, not Novaworks-specific user testing — worth validating with real users before treating the threshold as final.

Pending approvals (was Open Question 3): Users are nudged for pending approvals only when the approval's SLA has been breached — not for approvals that are merely pending but still within SLA.

Rationale: same restraint principle as the content-specificity decision above — the nudge should surface what's genuinely urgent, not everything that's technically outstanding. Nudging on every pending approval regardless of urgency would add noise and work against the fatigue risk already flagged below; gating on SLA breach holds approvals to the same "actually overdue" bar as tasks and notifications.

Threshold configurability (was Open Question 2): For MVP, the less-than-3-items list/count threshold is a fixed platform-wide value, not tenant-configurable. Engineering should implement it as a named constant/environment variable rather than a hardcoded literal, so it can be promoted to a per-tenant setting later without a rework — but no tenant-facing configuration surface ships in this release.

Rationale: no tenant has asked for a different threshold — at this stage it's a product decision, not a tenant one, so per the config-vs-code heuristic it belongs in code, not config. Building tenant-facing configurability ahead of demonstrated need is a well-documented MVP pitfall: it consumes engineering effort without adding user value now, and speculative config surfaces tend to calcify into feature-flag debt (settings nobody uses but everyone has to keep supporting). Real per-tenant configuration is worth investing in once actual tenant demand shows up, not preemptively.

Open Questions¶

These are carried directly from the PRD and must be resolved before implementation:

Should the nudge distinguish between notifications and overdue tasks, or present them as a single combined signal? (Partially addressed by the resolved content-specificity decision above, which separates counts by category — but the exact framing/wording is still open.) Now that SLA-breached approvals are also nudged, should they be counted as their own category (notifications / tasks / approvals) or folded into "overdue tasks"?

Section 4 — "Continue in Novaworks" Deep Link: the nudge's deep link should follow the same deep-link mechanism defined there.
Section 5 — Re-sync Chat with Host Surface: if a user acts on a nudge in the portal and later returns to the original chat surface, re-sync behavior determines whether that surface reflects the resolved state.

Risks¶

Risk	Severity	Mitigation
Nudge noise / fatigue	Medium	Resolve Open Question 4 (configurability) before rollout; avoid nudging on every single chat initiation if items are unchanged since the last nudge.
Transport support gap (A2A/MCP marked TBD)	Medium	Deep-link fallback (per compatibility matrix) ensures the capability degrades gracefully rather than failing silently on unsupported transports.
Nudge content exposes sensitive task/notification details in a low-trust host surface	Medium	Depends on resolution of Open Question 1; default to generic message until data-exposure review is complete.

Status: DRAFT — derived from PRD Section 2, dependent on unresolved open questions. For internal engineering review only.

Novaworks AI | Confidential