Skip to content

/onboard — Slash Command Spec

Not yet implemented. This page is a spec for a planned feature.

Commands

/onboard [@onboardee] [@onboarder]
/onboard availability list [optional:region]

/onboard [@onboardee] [@onboarder]

Signature

/onboard [@onboardee] [@onboarder]

Access

Representative+

Purpose

Assigns an onboarding buddy to a member currently in the vetting pipeline. Writes to $People.onboarding_buddy and logs the assignment timestamp.

Parameters

  • @onboardee — the member being onboarded. Resolved to $People via resolve_person(). Must exist in $People.
  • @onboarder — the buddy being assigned. Also resolved to $People. Must have remaining_capacity > 0 — bot checks and warns if at capacity.

Pre-flight Checks

Before writing:

  1. Onboardee exists in $People — error if not found
  2. Onboarder exists in $People — error if not found
  3. Onboarder has remaining capacity — $People.remaining_capacity > 0. If zero: warn operator: ⚠️ @bob is at onboarding capacity (0 slots remaining). Assign anyway? [Yes] [Cancel]
  4. Onboardee already has a buddy — if $People.onboarding_buddy is already set: ⚠️ @alice already has an onboarding buddy: @carol (assigned May 3). Reassign to @bob? [Yes] [Cancel]

Writes

On confirm:

  • PATCH $People[onboardee].onboarding_buddy → onboarder's $People row id
  • PATCH $People[onboardee].buddy_assigned_datetime → now (or leave to Grist default if API allows trigger)
  • PATCH $People[onboardee].buddy_ack → False (reset if reassigning)

Note: buddy_assigned_datetime has a _default trigger in Grist — confirm whether the Grist API respects column defaults on PATCH or whether the bot needs to send the timestamp explicitly. If the latter, bot sends current UTC timestamp converted to America/Los_Angeles.

Response

Ephemeral confirmation:

✅ Onboarding buddy assigned
  Onboardee: @alice
  Buddy: @bob
  Bob's remaining capacity after this: 2

Pair copy-paste: @bob - @alice

onboarding_pair_c_p is a pre-computed field on $People — read it back after the write for the copy-paste output rather than constructing it in the bot.

/onboard availability list [optional:region]

Signature

/onboard availability list
/onboard availability list [region]

Access

Representative+

Purpose

Returns a list of members who have onboarding capacity available, optionally filtered by region. Used by reps to find available buddies before running /onboard.

Parameters

  • region (optional) — autocomplete from region ChoiceList values. Filters by $People.discord_id_Region_roles_region.

Grist Fields Used

Query $People where remaining_capacity > 0, filtered optionally by region. For each result, display:

Display Field Notes
Handle default_handle Safe display name
Remaining capacity remaining_capacity Numeric
Total capacity capacity_onboarding Numeric
Most recently assigned most_recently_assigned_date Date
Buddies onboarded total_buddies_onboarded Numeric
Regions discord_id_Region_roles_region List

Response Format

Ephemeral embed:

🤝 Available onboarding buddies — South

  alice       2/3 slots free   last assigned: Mar 15   total: 8
  bob         1/2 slots free   last assigned: Apr 2    total: 3
  carol       3/3 slots free   last assigned: —        total: 0

Run /onboard @onboardee @buddy to assign.

Sorted by remaining_capacity descending, then most_recently_assigned_date ascending (longest since last assigned first).

Dev Notes

  • remaining_capacity is pre-computed: max(capacity_onboarding - assigned_since_capacity_timestamp, 0) — read directly, don't recompute
  • Region filter: discord_id_Region_roles_region is a list — filter where region string appears in that list
  • If no results: No onboarding buddies available + suggestion to check capacity settings in Grist

Open Questions

  1. buddy_ack field — what does this track exactly? Does the bot need to do anything with it beyond resetting on reassignment?
  2. Capacity reset — capacity_timestamp is used to scope assigned_since_capacity_timestamp. Should the bot expose a /onboard capacity reset [@member] command for reps to reset a buddy's capacity window? Or is that Grist-only?
  3. Notification to buddy — should the bot DM the assigned buddy when they get an onboardee? This is a good candidate for the notify() abstraction established in the RSVP P3 spec.
  4. Vetting pipeline gate — should /onboard assign require the onboardee to be in a specific status (e.g. unvetted (ready for vetting))? Or is status-agnostic assignment intentional?