Overview

The troubleshooting feature allows admins/hosts to understand why specific time slots or entire days are unavailable for booking. It is accessible via a "Start troubleshooting" toggle on the public booking page and is only visible to logged-in admins/hosts — clients never see it.

When troubleshooting is active:

• All time slots for the day are shown (not just available ones)

• Each slot shows "Available" or "Unavailable" with a help icon to see reasons

• Days that are entirely unavailable show a "Whole day unavailable" section with reasons

• Actionable reasons include a "Change" or "View" link to the relevant admin page

• Available slots may show info icons explaining why they're available

Key Changes From Current Implementation

Future Considerations

• Shareable troubleshoot link — a "Copy link" button to share the troubleshoot URL with customer support.

• NeetoChat fallback — Under "Questions about slots?", show "Still not able to figure out the issue? Chat with us." which opens NeetoChat. Only if NeetoChat is enabled for the organization.

• Slot flooding solution — When availability is 9–5, showing midnight-to-midnight slots creates noise. Options: collapse outside-availability slots into a band, or show only working-hours slots by default with a "Show all 24h" toggle.

• Expanded layout — Replace narrow slot-list + popover with a split panel view (calendar left, full-width reason panel right) where clicking a slot shows its breakdown inline.

• Outside availability as a distinct visual state — Dim/fade outside-availability slots instead of showing them as regular "unavailable" — they were never in play, which is different from "blocked by something."

---

Timezone Warning Modal

When troubleshooting starts, if the booking page timezone differs from the admin's profile timezone, a modal overlay appears.

The modal appears as a blurred backdrop overlay over the calendar. If the admin manually changes the timezone to match their profile, the modal auto-dismisses. No auto-switch button — admins who want to switch timezone do so manually via the timezone picker.

---

Calendar Day Styling

Day States

When a Day Turns Grey

A day turns grey in troubleshoot mode when ANY of:

• The date is in the past

• The backend marks it as fullyUnavailable

• The date has no slots in the API response

• All slots on the date have isAvailable: false

Grey days remain clickable in troubleshoot mode so admins can see why.

---

Day-Level Display: "Whole Day Unavailable"

When all slots on a day are unavailable, a summary card appears above the slot list.

• Card header: "Whole day unavailable because"

• Card body: Lists the day-level reasons (see table below).

Day-Level Reasons

These are reasons that block the entire day, not just individual slots.

[CHANGE] Added "Past Time" as day-level reason #0. This was discussed in the walkthrough video — when the entire day is in the past, a banner should appear rather than forcing users to click each slot.

Day-Level Detection

A day is marked fully unavailable when:

• The date is in the past

• All slots are blocked by a common reason (lead time, holiday, booking limits, date range)

• All members are outside their working hours (round-robin/multihost)

• All members have day-level blockers (round-robin/multihost)

---

Slot-Level Reasons — Complete Reference

Display Precedence Order

When multiple reasons apply to the same slot, they are displayed in this order (top to bottom):

All reasons are shown (not just the highest priority). This order only determines the display sequence within the popover.

Merging Priority (Backend)

When the backend merges conflicting reasons for the same slot, it keeps the higher-priority reason as the "primary":

---

Complete Slot-Level Reason Table

Each reason shows: Title (bold, text-xs font-bold), Message (grey, text-xs), and optionally an inline Change/View link after the message text.

1. Past Time

Slot is in the past. Grey out all past slots but show them as they were — whether available or unavailable. If unavailable, show the original reasons.

2. Date Range Exceeded

Slot falls outside the meeting's configured date range. Grey out all slots on the day, mark all as unavailable.

3. Outside Host's Availability

Slot is outside the host's configured working hours. Grey out slots outside availability. These slots are not shown in normal mode.

Change link visibility: Only show if the troubleshooting user is the host themselves or an admin.

Special rendering for host availability (single range):

{hostName} is only available from {start} to {end} as per {availabilityName}. [Change]

Special rendering for host availability (multiple ranges):

{hostName} is only available at the following times:

• 09:00 AM to 10:00 AM

• 11:15 AM to 12:15 PM

• 01:15 PM to 02:15 PM

As per {availabilityName}. [Change]

No working hours on the day:

{hostName} is not available on this day as per {availabilityName}. [Change]

4. Holiday

Day is marked as a holiday. Grey out all slots, mark all as unavailable.

5. Availability Override

Explicit override for a specific date.

Change link visibility: Only show if the troubleshooting user is the host themselves or an admin.

Special rendering (single range):

{hostName} is only available from {start} to {end} due to an availability override in {availabilityName}. [Change]

Special rendering (multiple ranges):

Same vertical list format, with "As per availability override in {availabilityName}." [Change]

For available slots (for all available slots):

Show help popover with message. This slot is available because of an availability override in {availabilityName}. [Change]

6. Lead Time

Lead time prevents near-term slots from being bookable.

7a. Meeting Limit — Scheduling Link

Booking limit reached at the scheduling link level.

7b. Meeting Limit — Host

Booking limit reached at the host level.

Change link visibility: Only show if the troubleshooting user is the host themselves (v1).

7c. Duration Exceeds Availability

Meeting duration extends past the end of the host's availability window. These slots are not shown in normal mode.

Change link visibility: Only show if the troubleshooting user is the host themselves (v1).

Implementation note: This reason must be generated by the backend. The prototype computes it on the frontend, but the production implementation should move this to time_frames_to_slots_service.rb.

7d. Overlapping Meeting — Internal (NeetoCal Booking)

Conflict with another booking made through NeetoCal. These are treated differently from external events because we can link directly to the booking.

Note: "View" link (not "Change") because this is an existing booking, not a setting.

7e. Overlapping Meeting — External Calendar Event

Conflict with an event from a connected external calendar.

iCloud Travel Time variant:

7f. Buffer Time

Buffer time from adjacent events eating into this slot. Two distinct cases:

Case 1: External event has its own buffer configured

Note: It is unclear whether this scenario can actually occur in practice. Keeping it documented for completeness, but engineering should verify if this case is possible before implementing.

The external event's buffer time bleeds into this slot.

Case 2: This scheduling link requires buffer, and an adjacent event prevents it

The scheduling link's buffer requirement can't be satisfied because of a nearby event.

Change link visibility: Only show if the troubleshooting user is the host themselves (v1).

Buffer from internal NeetoCal bookings:

8. Group Event Full

Maximum capacity reached for a group scheduling slot.

Other Slot-Level Reasons

Note: too_soon and members_unavailable must be generated by the backend. The prototype has translation keys but the reasons are not yet generated — they need to be added in the backend phase.

---

Available Slot Info

Available slots normally show no help icon. In these specific cases, an info (i) icon appears:

Available Due to Availability Override

When a slot is available because an override expanded hours beyond the original working hours:

Available But in the Past

When a slot was available but the time has now passed:

Available Due to Free External Event (Future consideration)

When an external calendar event is marked as "free" (not blocking):

To be specified in a future iteration.

---

Multi-Member Meetings (Round Robin & Multihost)

Behavior Differences by Meeting Type

Shared vs Host-Specific Reasons

For multi-member meetings, day-level reasons split into:

Shared reasons (shown once at the top, NOT repeated per host): Holiday, Lead time, Date range exceeded, Booking limits (scheduling-link-level: daily/weekly/monthly)

Host-specific reasons (shown per host): Host availability / no hours, Booking limits (host-level: daily/weekly/monthly)

When shared reasons exist (e.g., holiday), ALL hosts are treated as unavailable regardless of backend per-host status.

Per-Host UI

[CHANGE] Updated host section ordering for round-robin meetings. Per the walkthrough video, the order of "Available hosts" and "Unavailable hosts" sections should flip depending on whether the slot itself is available or unavailable. This helps users focus on the most relevant information first.

For unavailable slots (and all multihost slots):

• Unavailable hosts section (shown first):

  • Heading: "Unavailable hosts" (text error-600, body2, semibold)

  • Red pill badge: {count}/{total} (background error-100, text error-600)

  • Each host: 24px circular avatar + name (text-xs font-medium gray-800) + reasons expanded below

• Available hosts section (shown second):

  • Heading: "Available hosts" (text success-600, body2, semibold)

  • Green pill badge: {count}/{total} (background success-100, text success-600)

  • Each host: avatar + name only, no reasons

For available slots in round-robin meetings:

• Available hosts section (shown first):

  • Heading: "Available hosts" (text success-600, body2, semibold)

  • Green pill badge: {count}/{total} (background success-100, text success-600)

  • Each host: avatar + name only, no reasons

• Unavailable hosts section (shown second):

  • Heading: "Unavailable hosts" (text error-600, body2, semibold)

  • Red pill badge: {count}/{total} (background error-100, text error-600)

  • Each host: 24px circular avatar + name (text-xs font-medium gray-800) + reasons expanded below

No line separators between hosts. Reasons always expanded (no accordion).

Slot-Level Popover for Multi-Member

The popover shows:

• General reasons (meeting-level blockers) at top with inline links

• Host sections ordered as per the rules above (unavailable-first for unavailable slots; available-first for available round-robin slots)

Popover: min-width 400px, max-height 320px with vertical scroll.

---

Change Link Destinations Summary

Change Link Visibility Rules

Some change links should only be shown to the relevant host or to admins:

• Host availability, availability override, duration mismatch, host booking limits, buffer (case 2) -> show only if the troubleshooting user IS the host or is an admin

• All other change links -> always shown

---

Reason Item UI Layout

Title (text-xs font-bold)
Description text in grey (text-xs, gray-600). Change <- inline link

Slot hover: theme primary color with 0.15s ease transition.

---

Whole Day Unavailable — Layout Example

+-- Whole day unavailable because ------------------+
|                                                    |
|  Holiday                                           |
|  This day is marked as a holiday for Holi          |
|  in NeetoCal. Change                               |
|                                                    |
|  -- Multi-member only: -------------------------   |
|                                                    |
|  Unavailable hosts [5/6] <- red pill               |
|                                                    |
|  [avatar] Cypress User                             |
|    Host Availability                               |
|    Cypress User is only available from             |
|    09:00 AM to 05:00 PM as per                     |
|    Working hours. Change                           |
|                                                    |
|  [avatar] Oliver Smith                             |
|    Daily Limit                                     |
|    Daily booking limit of 5 has been reached       |
|    for Oliver Smith. Change                        |
|                                                    |
|  Available hosts [1/6] <- green pill               |
|                                                    |
|  [avatar] Jane Doe                                 |
|                                                    |
+----------------------------------------------------+
                See individual slots v

---

Known Engineering Considerations

These are edge cases and technical notes the engineering team should be aware of during implementation.

Timezone + Day Boundary

When the page timezone and host timezone differ significantly (e.g., host in IST, page in PST), a slot at 11:30 PM PST is actually the next calendar day in IST. This can cause day-level reasons (like holidays) to be applied incorrectly. The prototype has a known bug with holidays related to this. All day-boundary logic in time_frames_to_slots_service.rb must use the client timezone consistently.

Buffer Time: Two Distinct Cases

The backend already generates different reason keys for these — calendar_event_before/after_buffer (case 1: external event's buffer) vs slot_before/after_buffer (case 2: scheduling link's buffer requirement). These must remain separate because:

• Case 1 has no change link (admin can't change the external event's buffer from NeetoCal). Note: It is unclear whether this case can actually occur in practice — engineering should verify.

• Case 2 has a change link to the host availability page (admin can adjust the scheduling link's buffer setting)

Change Links Must Use Host-Specific URLs

When an admin troubleshoots a round-robin/multihost meeting, change links for host-specific reasons (availability, booking limits) must link to that host's settings page, not the admin's own. The URL should use the host's SID, not /host/self/.

Availability Override Detection

The override reason applies in two directions:

• Override contracted hours (slot was available but override made it unavailable) -> show override reason with "Change" link

• Override expanded hours (slot is now available because override added hours) -> show info icon: "available because of override"

The backend must track the original (pre-override) availability periods to distinguish which slots fall inside vs outside the original hours.