Configure Coach steps

This runbook is for Program Managers configuring a Coach step on a Goal that's already been added to a Program. By the end you'll have a Coach step a supplier can schedule with a real advisor on their action plan.

Prerequisites

Before you start, confirm:

• The Program and Goal already exist (visible under the Goals and Programs nav in /admin)
• Each Advisor you plan to assign has been onboarded — their Advisor row has completedAt set, a non-null calendlySlug, and active = true.
• You're logged into AdminJS at /admin with role admin or programManager

Concept map

A supplier sees an advisor on a coach step only when both the AdvisorStepAssignment and ProgramAdvisorAssignment exist (dual-assignment gate). Missing either side hides the advisor from the supplier's eligibility list.

Walkthrough

1. Create the Coach GoalStep

In AdminJS, navigate to Goals → Goal Steps → New and fill in:

• Goal — pick the goal you're configuring
• Type — COACH
• Title and Description — supplier-facing copy
• displayOrder — controls render order on the supplier's learning path; pick a value that fits the goal's existing sequence
• isActive — true (publish)

Saving creates the GoalStep and an empty CoachStep extension row linked to it.

2. Configure the session definition

Open Goals → Coach Steps, find the row whose goalStep matches the step you just created, and edit:

• sessionDurationMinutes — pick one of 15, 30, 60, 90, 120 (these match the Calendly managed event-type slugs ssa-coach-{n}min — values outside this set will break the supplier's "Schedule" CTA)
• sessionAgenda — one item per row, shown to the supplier under "In this session"
• preparationItems — one item per row, shown under "What to bring"

3. (Optional) Wire pre/post questionnaires

If the coach step needs a pre or post survey:

1. Go to Goals → Questionnaires → New, give it a name + description, and use the SurveyJS editor to define the schema. Save.
2. Go back to the Goal Step record (step 1) and edit it. Set preQuestionnaireId and/or postQuestionnaireId to the questionnaire(s) you just created. Save.

The pre-questionnaire blocks the supplier from booking until they fill it out; the post-questionnaire blocks the step from completing until they fill it out after the session.

4. Verify each advisor is eligible

In Users & Advisors → Advisor Profiles, confirm for every advisor you plan to assign:

• active is true
• completedAt is set (advisor finished onboarding)
• calendlySlug is set (Calendly account is provisioned)

Advisors that don't satisfy all three will be hidden from the assignment dropdowns in the next two steps.

5. Assign advisor → Coach Step

Navigate to Program Relations → Advisor Step Assignments → New, choose:

• Advisor — the advisor profile (only fully onboarded advisors appear)
• Coach Step — the step from steps 1–2

Save. The unique constraint on (advisorId, coachStepId) means re-saving the same pair will surface a validation error rather than create a duplicate.

Repeat for each advisor that should appear on this coach step.

6. Assign advisor → Program

Navigate to Program Relations → Program Advisor Assignments → New, choose:

• Program — the program the supplier is enrolled in
• Advisor — the same advisor
• Status — ACTIVE

Save. Same uniqueness rule — (programId, advisorId) is unique.

7. Sanity check as a supplier

Log in as a supplier in the program (an existing test account is fine), navigate to the goal's learning path, and open the coach step. The advisor(s) you assigned should appear in the eligibility list with their photo, expertise, and a "Schedule" CTA wired to their Calendly slug.

If the advisor isn't showing, re-check the dual gate (steps 5 + 6) and the eligibility flags (step 4).

Eligibility rules (reference)

The supplier-facing list of advisors is filtered by these rules. An advisor is eligible only when ALL of these are true:

Any single missing condition hides the advisor — there's no per-advisor warning surfaced to the PM today, so when a supplier reports a missing advisor, walk through this checklist first.

Common pitfalls

• Duplicate assignments — assigning the same advisor to the same coach step twice (or the same advisor to the same program twice) surfaces a validation error rather than creating a duplicate.
• Incomplete advisor profile — silently hidden from the assignment dropdowns. Cross-check the advisor's profile fields if they don't appear.
• Coach step missing sessionDurationMinutes — the supplier's "Schedule" CTA breaks because the Calendly slug template (ssa-coach-{n}min) has no n. Always set this before going live.
• Deleting an AdvisorStepAssignment does NOT cancel existing bookings — CoachStepSession rows survive advisor unassignment. Suppliers who already booked keep their session. To cancel, do it in Calendly directly (the webhook will sync status).
• displayOrder collisions — two steps with the same displayOrder produce non-deterministic ordering on the supplier's learning path, which can cascade into surprising "locked" states. Keep values unique within a goal.
• Questionnaire FK fields are hidden in the AdminJS GoalStep edit form — the relations show in the detail/show view, but to attach you have to set preQuestionnaireId / postQuestionnaireId on the GoalStep record (step 3 above).

Quick reference

• Related runbooks: Configure Learn steps, Configure Do steps