Onboarding Checklist (Dashboard)
Feature Overview
After a doctor finishes the lean 3-step sign-up and pays, the rest of their setup happens inline on the dashboard via the Getting Started checklist — there is no separate Setup Wizard (removed in #8027). The checklist lists every outstanding setup task; each step's tick is derived live from real data, and the whole widget auto-hides once everything is complete.
It is the single, surviving onboarding surface and replaces the deleted Phase 2 Setup Wizard. This spec owns the checklist mechanism; the surfaces each step links to (My Profile, CPD, Wellness, Logbook, Appraisals) are owned by their own feature specs, and the sign-up flow that precedes it is owned by Onboarding & Sign-up.
instances/ppp/src/components/OnboardingChecklist/index.tsx, backed by onboarding.getStatus in api/backend-ppp/src/services/identity-and-profile/onboardingService/index.ts. It is mounted on two surfaces only: CPD Home (CPDHomeV2, modules/cpd/dashboard/index.tsx) renders OnboardingChecklist for CPD-only doctors, and the PPP Dashboard (/ppp-dashboard, full-platform doctors) renders its own "Outstanding Onboarding" section, OnboardingSection (modules/admin-org/ppp-dashboard/sections/OnboardingSection.tsx), from the same onboarding.getStatus data. The legacy Dashboard module was retired (#8432) and mounts nothing.
Checklist steps
Each step is shown when relevant to the user and ticked from live data. A CPD-only doctor sees 5 steps (6 if a surgeon); a full-platform doctor up to 12 (consultant surgeons see no surgical-target step; only consultants see Nominate your appraiser).
- Complete your profile — regulatory body, registration number, Default Working-Calendar Start, and (non-consultants) supervisors →
/my-profile(CV is captured at sign-up and managed in the PPP Passport (#9196), not on My Profile). Payroll ID is required for full-platform doctors (Matt 2026-07-14; Rob's #10594 decision 2026-07-17). Built in #12728. See Visibility & return below. - Create your first CPD plan →
/cpd-plans?newPlan=1(fixed from?add=1in #12549 — on/cpd-plans,add=1is the open-state of the Annual Reflection dialog, so the step opened the end-of-year reflection form on top of the plan editor) - Log your first CPD activity →
/cpd-activities - Complete a wellness questionnaire → opens inline (#7350)
- Connect your data — wearable connection on the Wellness Data Sources page; ticks only on a verified connection (#7341) →
/wellness/settings(formerly/wellness?tab=data-sources— fixed in #9254; a/wellness/data-sourcesredirect alias also exists) - Set your surgical case targets — non-consultant surgeons only (T7-16, Rob 2026-10-05: consultants have no whole-of-training case total and the My Profile cadence card shows them only MSF and 360, so the step could never tick; it is not listed for consultant surgeons). Case targets are set on the My Profile cadence card (
/my-profile#cadence) and in the Surgical Logbook widget's "Set Case Targets" dialog (CadenceTargetsDialog) (drift: Matt 2026-09-29 wants every doctor to confirm their WBA/appraisal cadence as part of onboarding, seeonboarding-checklist.cadence-confirm-step, #12729); ticks when a whole-of-training total is set incadenceTracker→/my-profile#cadence(#8027). The cadence model itself is specified in onboarding.md (onboarding.cadence.*). - Set your appraisal date — full-platform doctors only (#12675): the Appraisals area is not part of the CPD-only plan, so the step is not listed for CPD-only users →
/appraisals/upcoming?setAppraisalDate=1, which opens a lightweight "When is your appraisal?" prompt (a date; saved to theperiodEndof the appraisal for that date's year viaappraisalWorkflow.setAppraisalDate, #12787, Rob 2026-10-04). Saving ticks the step (it ticks once an appraisal row exists). The full 8-step Appraisal Form is unchanged and has no date input. The date shows on the Appraisals page header ("Appraisal date: …") and is editable there. The prompt also takes an optional appraiser (#12879, built). (Earlier:?openAnnualForm=1, fixed from?add=1in #8948.) - Import your logbook — full-platform doctors only (#12550): the logbook is not part of the CPD-only plan, so the step is not listed for CPD-only users →
/logbook-case?import=1(#7849) - Use Smart GeoTag to enter first timesheet entry — full-platform doctors only (#7634) →
/my-profile#hospitals; ticks once the doctor has any timesheet, whether Smart GeoTag-sourced or entered manually (T7-28; the earlier code matched geofence-sourced rows only, contradicting the TODO(#5333) fallback rule) - Confirm your WBA cadence — full-platform doctors (#12729) →
/my-profile#wba-cadence; ticks once a WBA/appraisal count is saved (the profile form never persists an unconfirmed default). - Add your hospital — full-platform doctors (#9173) →
/my-profile#hospitals; ticks once a hospital is linked. Listed before Smart GeoTag because linking a hospital is the first Smart GeoTag setup step. - Nominate your appraiser — consultants on a full-platform plan only (#9173) →
/my-profile#supervisors; ticks once the Colleague Appraiser is set. Non-consultants' supervisors are covered by "Complete your profile". - Upload your CV — full-platform doctors (#12876) →
/ppp-passport?tab=cv; ticks once a CV file exists (CV is optional at sign-up, #12783).
The list above is in documentation order; the live order and the exact set per persona come from getOnboardingStatus (onboardingService/index.ts). A full-platform consultant sees up to 12 of these 13 (no surgical-target step); a non-consultant surgeon sees 12 (no Nominate your appraiser).
Where the old wizard steps went (#8027). CV upload is captured at sign-up and managed in the PPP Passport (#9196) — it was removed from My Profile (Rob, 2026-06-24), a settings page being the wrong home for a portable record; immunisations move into the PPP Passport (
HrPassportPage→ImmunisationsCard), never the sign-up flow; supervisors + placement are covered by "complete your profile"; cadence targets are edited on the My Profile cadence card; wearables connect from the Wellness Data Sources page.
No "answer-once" skip (#8027)
The checklist has no per-step Skip, no "Restore skipped steps", and no whole-section "Skip onboarding". Every step always reflects live completion, so nothing can be marked done that isn't. The only dismissal is the checklist close button, intended for once everything is genuinely complete (onboardingCompletedAt). The close button is therefore only rendered once every step is complete, the server refuses a dismissal while any step is open, and a checklist that was dismissed while steps were still open is shown again until they are done (#12551). The former skip columns (onboardingWizardCompletedAt, onboardingReminderAt, dismissedOnboardingSteps, onboardingDismissedAt) were dropped (migration 0151_warm_bucky).
Open Questions
The checklist model and the "no answer-once skip" decision were settled under #8027; this spec is the split-out of that already-agreed design. These questions are open:
- OQ-OC1 — should a CPD-only user see "Import your logbook" as an upgrade prompt instead of not at all? (#12550) The step was specified as shown to "All users" (#7849, Dev Session 2026-04-01), but the logbook itself is full-platform only (#4881), so for a CPD-only user the step dead-ended on "This feature is not available on your current plan". Neither source says what a CPD-only user should see. Engineering has hidden the step for CPD-only users as the safe default (nothing is offered that cannot be completed). The alternative is to keep a row for CPD-only users that is presented as an upgrade prompt to the full plan rather than as a checklist step. That is a product and pricing-surface decision for Matt — it is not inferred here. Note that an upgrade row would need a rule for the progress count and for
allComplete, since a CPD-only user could never tick it. - OQ-OC2 — should a CPD-only user see "Set your appraisal date" as an upgrade prompt instead of not at all? (#12675) Same shape as OQ-OC1: the Appraisals area (
/appraisals/upcoming) is full-platform only, so the step dead-ended for CPD-only users. Engineering hid the step as the safe default, matching #12550's precedent; the upgrade-prompt alternative is the same open product/pricing decision for Matt. - OQ-OC3: does a CPD-only user also need a payroll ID before "Complete your profile" ticks? (#12728) On 2026-07-14 Matt said the profile "shouldn't be complete until … all the items are completed". He said it after noticing the gap while doing his timesheet. Payroll ID is only used for timesheets, and timesheets are full-platform only.
onboarding-checklist.profile-payroll-id-requiredtherefore requires it for full-platform doctors only. Matt has not said whether CPD-only users are exempt. Applying the requirement to them would block their profile tick on a field they never use. - OQ-OC4: should the checklist ask the doctor to set a regular wake time? On 2026-07-14 (~00:37:41) Matt said: "maybe we just ask the user to set set their wake time as part of the onboarding um regular wake time and then just have … the ability to click on in the guidance … and just change it". The wording is tentative ("maybe"). The wake target is now detected from sleep data, with a user preference and a 06:30 fallback (
wellness.sleep.wake-target-shown, #10183 / #10603). Neither source says whether it should also be a Getting Started step. No AC has been added. OQ-OC5: what counts as "confirming" the cadence, and is it one step or two? (#12729)Resolved (Rob, 5 Oct 2026): saving the profile counts as confirming. Matt wants defaults that the user confirms as part of onboarding: surgical totals "default but flagged it for review/confirmation" (2026-09-21) and WBA/appraisal cadence "User to confirm as part of onboard" (2026-09-29). The My Profile form pre-fills a curriculum default for the surgical total (useUserFormLogic.ts, #8552); saving the profile therefore stores that default and ticks the step, and Rob has decided that is the intended behaviour. The Task 7 code is unchanged. Still open for Matt: whether the surgical and WBA halves should be one checklist step or two.
Acceptance Criteria
Checklist mechanism (#8027)
The Phase 2 Setup Wizard was removed and onboarding consolidated into this dashboard Getting Started checklist.
- ✅ Onboarding lives only in the dashboard checklist — there is no
/onboardingsetup-wizard route and no first-login wizard redirect (#8027;code:instances/ppp/src/App.tsx,code:instances/ppp/src/PppModules.tsx).† - ✅ Each checklist step's completion is derived live from real data, and the widget auto-hides once every step is complete (#8027;
code:api/backend-ppp/src/services/identity-and-profile/onboardingService/index.tsgetOnboardingStatus,code:instances/ppp/src/components/OnboardingChecklist/index.tsx). - ✅ The checklist has no per-step Skip, no "Restore skipped steps", and no whole-section "Skip onboarding" — nothing can be marked done that isn't (#8027).†
- ✅ Immunisations are captured in the PPP Passport, never the sign-up flow (#8027;
code:instances/ppp/src/modules/HrPassport/HrPassportPage.tsxrenderscode:instances/ppp/src/modules/PppPassport/components/ImmunisationsCard.tsx).† - ✅ A "Connect your data" checklist step deep-links to the Wellness Data Sources page and ticks only on a verified wearable connection (
data_source_connectionstatusconnected), not on merely opening an OAuth flow (#8027 / #7341;code:api/backend-ppp/src/services/identity-and-profile/onboardingService/index.ts). - ✅ A non-consultant-surgeon-only "Set your surgical case targets" (T7-16) checklist step deep-links to the My Profile cadence card (
/my-profile#cadence) and ticks when a whole-of-training total is set incadenceTracker(#8027;code:instances/ppp/src/modules/MyProfile/UserForm/index.tsx). - ✅ "Use Smart GeoTag to enter first timesheet entry" step shown to all full-platform (PPP) doctors regardless of payroll ID — gated on full-platform access, not on
payrollId; hidden for CPD-only and admin accounts (#7634 / #7656;code:api/backend-ppp/src/services/identity-and-profile/onboardingService/index.ts) - ✅ An "Add your hospital" checklist step is shown to full-platform (PPP) doctors and ticks once any hospital is linked (
user_assigned_hospitalshas a row) — it is the prerequisite that unlocks Smart GeoTag, timesheet-approver suggestions and the hospital-scoped supervisor picklist, and is ordered before the Smart GeoTag step (#9173;code:api/backend-ppp/src/services/identity-and-profile/onboardingService/index.tsstep idaddHospital). The supervisor-model rationale is specified in profile-doctor.md (profile.onboarding.add-hospital-step). - ✅ A "Nominate your appraiser" checklist step is shown to consultants (hidden for CPD-only and admin accounts) and ticks once a Colleague Appraiser is set (
users.colleagueAppraiserId); it replaces the former always-shown cosmeticrequiredasterisk on the profile field, which was never enforced (#9173;code:api/backend-ppp/src/services/identity-and-profile/onboardingService/index.tsstep idnominateAppraiser). Specified in profile-doctor.md (profile.supervisor.appraiser-nudge-not-hard-required). - ✅ Completing onboarding routes the user to the access-appropriate dashboard —
/ppp-dashboardfor full CPD+PPP users,/cpd-dashboardfor CPD-only — matching the post-login landing logic (#7356;code:instances/ppp/src/utils/landingPath.ts) - ✅ The Setup Wizard tracking + per-step skip columns (
onboarding_wizard_completed_at,onboarding_reminder_at,dismissed_onboarding_steps,onboarding_dismissed_at) were dropped (#8027; migrationpackages-shared/ppp/drizzle/0151_warm_bucky.sql). - ✅ "Complete a wellness questionnaire" from the onboarding checklist opens the questionnaire inline rather than navigating away (#7350)
- ✅
onboarding-checklist.dismiss-only-when-complete— the checklist close button is rendered only once every step is complete, andonboarding.completeOnboardingrejects (PRECONDITION_FAILED) while any step is still open, so the checklist cannot be hidden with work outstanding. The widget is hidden only when it has been dismissed and nothing is outstanding, so a user who dismissed it earlier with steps still open sees it again, with no data migration and no separate "restore" control (consistent withNo "answer-once" skip).†‡ (#12551) - ✅
onboarding-checklist.profile-banner-no-dismiss— the same "No answer-once skip" rule applies toProfileCompletionGuard's site-wide "Complete your profile" banner, not just the dashboard checklist widget. It predated #12551 (built for #3711, before the rule existed) and was never brought in line with it: it dismissed viasessionStoragewith no reopen affordance, so a user who clicked the X lost the banner for the rest of the browser session even though the profile was still genuinely incomplete. The banner now has no dismiss control at all — since it only ever renders while the profile is incomplete, "can only dismiss once complete" leaves no state in which dismissing it is legitimate.†‡ (#12664) - ✅
onboarding-checklist.cpd-plan-step-opens-editor-only— the "Create your first CPD plan" step opens the CPD plan editor and nothing else: it deep-links to/cpd-plans?newPlan=1, a param only the plan editor reads. It must never carryadd=1, which on that page opens the Annual Reflection (end-of-year) dialog. Both onboarding surfaces resolve the step route by step id, so the step stays correct when the frontend and backend are deployed at different times.†‡ (#12549) - ✅
onboarding-checklist.import-logbook-full-platform-only— the "Import your logbook" step is listed for full-platform doctors only (accountAccesscpdppporppp), gated the same way as the Add-your-hospital and Smart GeoTag steps. A CPD-only user is never offered it, because the logbook backend rejects CPD-only callers and the step could only dead-end on the plan wall. Whether CPD-only users should instead see an upgrade prompt is open question OQ-OC1.†‡ (#12550) - ✅
onboarding-checklist.appraisal-date-full-platform-only— the "Set your appraisal date" step is listed for full-platform doctors only (accountAccesscpdppporppp), gated the same way as Import your logbook. A CPD-only user is never offered it, because its route (/appraisals/upcoming) is gated to full-platform accounts (RequirePppAccess) and the step could only dead-end on the plan wall. Whether CPD-only users should instead see an upgrade prompt is open question OQ-OC2.†‡ (#12675) - ✅
onboarding-checklist.loading-placeholder-no-shift— whileonboarding.getStatusis loading, both checklist surfaces (PPP Dashboard "Outstanding Onboarding" section, CPD Home "Getting Started" widget) hold the checklist's space with a skeleton placeholder sized from the shape this browser last saw it take (shown or hidden, step count, and the card's rendered height with the viewport width it was measured at — remembered per surface in localStorage, tagged with the signed-in user, as a per-viewer convenience, never as state), so the card does not arrive late and push the page down; at the same viewport width the measured height is reserved exactly (row estimate otherwise, since titles and step descriptions wrap on a phone); a checklist that was hidden here last time reserves nothing, an unknown memory — or one written for a different user on a shared browser — reserves a full checklist, and a failed status load is not remembered. CPD Home holds the space while the current user is still loading only if the checklist was shown there before. The status query is sent on its own (skipBatch) rather than in the page's request batch, so it no longer waits on the slowest sibling procedure.†‡ (#12554) - ✅
onboarding-checklist.import-logbook-partial-complete— the "Import your logbook" checklist step is a tri-state, not a flat boolean: not started (no import yet), partially complete (at least one case imported but some rows still have a non-exact procedure match or an unmatched hospital — the same near-match/hospital resolution the import wizard already offers, never a block on completing the import itself perlogbook.import.confirm-matches-in-wizard/logbook.import.unmatched-hospital-no-block), or complete (imported with zero rows outstanding). A partially-complete step stays unticked and surfaces anoutstandingCount, rendered as "Partially complete — N imported cases still need a procedure/hospital match reviewed"; the whole-checklistallCompletegate is unaffected by this AC (it already required every step'scompletedflag, so a partially-complete import step already keeps it false) — this AC only stops the import step from lying about being done.†‡ (#10130) - ✅
onboarding-checklist.shown-to-consultants-and-non-consultants— the outstanding-onboarding checklist is shown on the dashboard to both consultant and non-consultant doctors. Neither surface gates the widget on user type: the PPP Dashboard "Outstanding Onboarding" section and the CPD Home "Getting Started" widget. User type only changes which steps are listed, for example supervisors for non-consultants and "Nominate your appraiser" for consultants.†‡ (#11189) - ✅
onboarding-checklist.surgical-target-default-flagged— a surgeon's whole-of-training case total is pre-filled from a default: the curriculum figure for their speciality, where one exists. The field says where the figure came from and asks the doctor to edit it if their number differs. The "Set your surgical case targets" step deep-links to it so it can be reviewed as part of onboarding. What counts as "confirmed" is still open (OQ-OC5).†‡ (#8552) - ✅
onboarding-checklist.cadence-confirm-step— built (#12729). A separate "Confirm your WBA cadence" step (confirmWbaCadence) is listed for every full-platform doctor, surgeon or not, consultant or not (consultants since #12806, when the Cadence Tracker began showing them MSF and 360). It ticks only once a WBA/appraisal count is saved, because the profile form never persists an unconfirmed default (stripUnconfirmedCadenceDefaults). The defaults are owned byappraisals-wba.mdwba.cadence.default-values(#12717). CPD-only doctors are not asked. The surgical-total step (cadenceSettings) is separate and non-consultant-surgeon only. One step per half is an engineering assumption on OQ-OC5, not a Matt answer.†
Visibility & return
- ✅ The Getting Started checklist is visible on the dashboards until onboarding is complete, then auto-hides — there is no separate completion banner (#8027; the
OnboardingOutstandingBannerwas removed; the checklist is mounted on CPD Home viaOnboardingChecklistand on the PPP Dashboard viaOnboardingSection, see Overview). - ✅ Returning users see live outstanding steps in the checklist (no stored "skipped" state); completion always reflects real data (#8027;
code:api/backend-ppp/src/services/identity-and-profile/onboardingService/index.ts). - ✅
onboarding-checklist.profile-payroll-id-required— Built in #12728. For full-platform doctors (accountAccesscpdppp/ppp), Payroll ID is a required field for "Complete your profile". A doctor without one stays unticked and is listed an outstanding "Payroll ID" item. Every profile-completion surface shares onepayrollIdrule so they can never contradict: the checklist, the guard redirect and banner, and the outstanding items. The My Profile completion panel was removed in #12875 (Rob, 2026-10-04). Whether CPD-only users are exempt is OQ-OC3. Superseded: the earlier "Payroll ID is OPTIONAL and never gates profile completion" rule (#7634 / #7656, 2026-05-27) was an engineering inference. Its cited sources, #7348 and #7358, are Matt's reports about missing dashboard widgets and logbook, not statements about payroll. Matt's 2026-07-14 statement and Rob's 2026-07-17 decision on #10594 replace it. PR #10770's claim that "Rob's decision (2026-07-17): payroll ID remains OPTIONAL" contradicts the written 2026-07-17 decision, which says "incl. payroll ID", and is not a source.††‡ (#12728) - ✅ Default Working-Calendar Start (
jobContractStartDate) IS a base requirement for "Complete your profile" — alongside regulatory body and registration number, on every profile-completion surface (checklist, guard redirect, outstanding-items banner; the My Profile completion panel was removed in #12875). The My Profile form pre-populates the picker with 1 February (AU default) rather than leaving it blank, so a first-time visitor sees a real value to accept or change instead of an empty field with no visible default. The pre-filled February is a real pending change (the form's baseline stays the saved value, null when unset), so it is sent on the next profile save/autosave and re-picking February also saves (#12786; #10594;code:api/backend-ppp/src/services/identity-and-profile/onboardingService/index.tshasBaseProfileFields,code:instances/ppp/src/components/ProfileCompletionGuard/index.tsx,code:instances/ppp/src/PppModules.tsx,code:instances/ppp/src/hooks/useOutstandingItems.ts,code:instances/ppp/src/modules/identity-profile/UserForm/hooks/useUserFormLogic.ts).†† - ✅
onboarding-checklist.upload-cv— the CV does NOT gate "Complete your profile" and the outstanding-items list never shows a "CV / resume" row (#9221), but the Getting Started checklist has its own "Upload your CV" step for full-platform doctors (#12876). It ticks oncecvFileis on file and deep-links to the Passport CV tab (/ppp-passport?tab=cv), where the CV is uploaded or replaced. The CV is optional at sign-up (#12783), so this is the nudge for a doctor who skipped it. It supersedes the earlier "CV is not a checklist item" rule, which existed only because My Profile had no upload surface. (#9221;code:instances/ppp/src/hooks/useOutstandingItems.ts,code:api/backend-ppp/src/services/identity-and-profile/onboardingService/index.ts). - ✅ "Complete a wellness questionnaire" from the onboarding checklist opens the questionnaire inline (in-place modal) rather than navigating to Wellness, on both places the checklist renders — the full-platform
OnboardingSectionwidget (#7350) AND the sharedOnboardingChecklistcomponent CPD-only doctors see on CPD Home (#12673; before this, CPD-only doctors were navigated away to/wellness?openQuestionnaire=1, leaving the dashboard entirely, because the inline interception was only ever wired into the full-platform widget). (code:instances/ppp/src/modules/PPPDashboard/useInlineQuestionnaire.tsx,code:instances/ppp/src/components/OnboardingChecklist/index.tsx)
Spec refresh — dated requirement ledger (2026-10-03)
Async Task 7 (#11189). The newest dated statement from Matt wins. Rob's acting-PO decisions apply only where Matt has not spoken since. Rob's own Task 7 walkthrough reviews (#12549–#12554, #12664, #12670–#12676) are engineering findings, not Matt statements. They are already reflected in the ACs above.
| Date | Source | Matt said (verbatim excerpt) | Effect on this spec |
|---|---|---|---|
| 2026-03-23 | #3539 issue body | "make it clear what areas of the platform are not complete and … steps the user through the onboarding requirements and in turn shows the full capability of the platform" | Origin of the checklist. CONFIRMS the mechanism |
| 2026-04-29 | PPP Dashboard Notion page (last edited) | "Function: 1. Outstanding onboarding" … "Onboarding Wizard — add - Use Smart Geotag to enter first timesheet entry" | CONFIRMS the Smart GeoTag step (#7634) |
| 2026-05-24 | #7350 issue body | "clicking on complete wellness questionaire from onboarding widget and it takes me to wellness to then have to find the button" | CONFIRMS the inline questionnaire (#7350, #12673) |
| 2026-05-24 | #7356 issue body | "I would think I should landed in PPP Dashboard" | CONFIRMS access-appropriate landing (#7356) |
| 2026-06-02 | transcript 2026-06-02 (#8027) | Remove the Phase 2 Setup Wizard; immunisations belong to the PPP Passport | CONFIRMS the checklist mechanism and No answer-once skip |
| 2026-07-07 | transcript 2026-07-07 (#10130) | "Don't allow the onboarding wizard to be marked as complete. … maybe we can say partially complete … how many are left to be resolved" | CONFIRMS import-logbook-partial-complete |
| 2026-07-14 | transcript 2026-07-14 (~00:16:20) | "I hadn't um put in my payroll ID … the profile shouldn't be complete until the items on the onboarding wizard until all the items are completed" | Supersedes the 2026-05-27 engineering "payroll optional" rule → profile-payroll-id-required ⚠️ (#12728); OQ-OC3 |
| 2026-07-14 | transcript 2026-07-14 (~00:16:20) | "monthly work year starts default February um that it didn't have a default in there" | CONFIRMS the work-year-start gate and February pre-fill (#10594) |
| 2026-07-14 | transcript 2026-07-14 (~00:25:29) | "revise … with the onboarding wizard … what gets that tick created because … even though it says I'm completed … there's many things that I still had to complete" | Same thread as #10594. Rob's 2026-07-17 decision gives the field list: "incl. payroll ID and work-year-start" |
| 2026-07-14 | transcript 2026-07-14 (~00:37:41) | "maybe we just ask the user to set set their wake time as part of the onboarding" | Tentative → OQ-OC4, no AC |
| 2026-07-29 | #11189 issue body (Task 7 brief) | "Show user (both consultant and non consultant) completion outstanding onboarding wizard" | New AC shown-to-consultants-and-non-consultants ✅ |
| 2026-09-21 | #11144 comment | "Surgical case volume … We should default but flagged it for review/confirmation as part of onboarding" | New AC surgical-target-default-flagged ✅; OQ-OC5. The default values belong to onboarding.md and were handed off on #12720 |
| 2026-09-29 | #11144 comment | "default WBA's cadence … User to confirm as part of onboard (which i believe this exists for WBA's cadence in profile)" | New AC cadence-confirm-step ⚠️ (#12729). Values are owned by wba.cadence.default-values (#12717) |
| 2026-09-30 | #11189 comment | "Rob review --> required changes --> re-record after changes completed --> Matt review and feedback" | Process only, no AC |
Not a source: PR #10770's body, and the code comment it introduced, both say "Rob's decision (2026-07-17): payroll ID remains OPTIONAL". The decision Rob actually wrote on #10594 that day says "incl. payroll ID". The spec follows the written decision together with Matt's 2026-07-14 statement.
Superseded by #8027 — Phase 2 Setup Wizard ACs (collapsed)
The Phase 2 Setup Wizard was removed in #8027 and replaced by this checklist. These ACs are retained for traceability; the behaviour lived in modules/Onboarding/ (deleted) and the onboardingTracking router/service (deleted), preserved in git history.
- ✅ Stepper UI with skip/save-for-later on every step
- ✅ Roadmap step: supervisors, placement, agreement (#3705)
- ✅ CV upload step (#3698) and CV upload file-type/size validation (#7925)
- ✅ Immunisations upload step (#3701) and validation (#7925)
- ❌ Educational Agreement upload — won't-do: never a product requirement, removed with the wizard (#8027) and not rebuilt (#8074 / #8163). The shared drag-and-drop panel it introduced (#7925) lives on instead at the CV upload step.
- ✅ Mobile compact "Step N of M" progress bar (#7925)
- ✅ New users redirected to
/onboardingafter first login (#4412) - ✅ First-login redirect suppressed for deferred users; Save for Later + outstanding-items banner (#7337)
- ✅ Save for Later persists the durable cross-device defer signal, awaited + retried (#7952)
- ✅ Road Map single primary action (#4904) and privacy-first supervisor copy (#7343)
- ✅ Connect Your Data step QR codes (#5599); ErrorBoundary no crash-loop (#5146)
- ✅ Completed steps retain state on re-entry (#4902); stepStatuses merge (#5145); consistent "Skip for now" (#4905)
- ✅ Profile completion banner + return notification via outstanding-items banner (#3601/#3602)
Status
| Sub-feature | Status | Notes |
|---|---|---|
| Dashboard onboarding checklist | ✅ Built | Single onboarding surface (#8027) |
| Connect-your-data step | ✅ Built | Verified-connection tick (#8027 / #7341) |
| Cadence step → My Profile | ✅ Built | Non-consultant surgeons only (T7-16), deep-links /my-profile#cadence |
| Smart GeoTag onboarding step | ✅ Built | Full-platform doctors (#7634) |
| Immunisations in PPP Passport | ✅ Built | Moved out of sign-up (#8027 / #7338) |
| No answer-once skip | ✅ Built | Live completion only (#8027) |
| Payroll ID gates profile tick | ✅ Built | Full-platform doctors; #12728 (OQ-OC3) |
| Cadence confirm for all | ✅ Built | Trainees and consultants; #12729 (OQ-OC5 resolved 5 Oct: saving the profile counts) |
| Leave-site prompt on My Profile | ✅ Built | Only real edits raise it; the prefilled February default does not (#12952) |
| Roadmap appraisal rows once | ✅ Built | Concurrent refreshes serialised per user (#12953) |
Open issues on label:feature:onboarding-checklist — no open issues. Fetched at: 2026-10-13T07:29:49Z — live list on GitHub.
Change Log
| Date | Change | PR/Issue | Reason |
|---|---|---|---|
| 2026-10-05 | Spec refreshed to the shipped checklist. The step list now names all 13 steps (adds Confirm your WBA cadence, Add your hospital, Nominate your appraiser, Upload your CV), the step cap is 12 per persona, the appraisal-date prompt's optional appraiser is marked built (#12879), the cadence-confirm-step AC is one consistent statement, and the code-paths glob now also covers OnboardingSection.tsx. OQ-OC5 records Rob's 2026-10-05 decision that saving the profile counts as confirming the surgical default. Status rows added for the Leave-site fix (#12952) and the Roadmap duplicate-row fix (#12953). | #11189, #12952, #12953 | Task 7 spec review (5 Oct 2026) found the spec stale against code (S1 to S4) and Rob decided the OQ-OC5 saving question on 5 Oct. The two fixes change user-visible behaviour on My Profile and the Roadmap. |
| 2026-10-04 | Added a "Confirm your WBA cadence" checklist step for full-platform non-consultant doctors (surgeon or not), ticking once a WBA count is saved. The "When is your appraisal?" prompt gained an optional appraiser picker (#12879). | #12729, #12879, #11189 | Matt 2026-09-29 (#11144) wants the default WBA cadence confirmed as part of onboarding; Rob 2026-10-04 (#12553) wants the appraisal prompt to take a date and an optional appraiser. Consultants stay drift until #12806 shows them the Cadence Tracker. |
| 2026-10-04 | The "Set your appraisal date" step now opens a lightweight "When is your appraisal?" date prompt (/appraisals/upcoming?setAppraisalDate=1) instead of the 8-step Appraisal Form. Saving stores the date in the periodEnd of that year's appraisal (new appraisalWorkflow.setAppraisalDate) and ticks the step; the date shows on the Appraisals page header and can be changed there. The optional appraiser in the prompt is not built yet. | #12787, #11189 | The Appraisal Form has no date input, so the step could never be completed. Rob decided on 2026-10-04 (#12787) on a lightweight date prompt. No schema change: the date reuses appraisals.periodEnd, which the Roadmap milestone engine already reads as the appraisal meeting. |
| 2026-10-04 | Removed the "Complete Your Profile" panel (ProfileCompletionStatus) from My Profile. Profile completion is still tracked by the Getting Started checklist step "Complete your profile", the ProfileCompletionGuard redirect and banner, and the outstanding-items list, all on the same shared rule. The panel is no longer listed as a profile-completion surface. | #12875, #11189 | Rob's decision on 2026-10-04 during the Async Task 7 review. The panel repeated what the dashboard checklist already tracks, and the form highlights missing required fields itself. |
| 2026-10-04 | Added an "Upload your CV" checklist step for full-platform doctors, ticking once a CV is on file. It deep-links to the Passport CV tab (/ppp-passport?tab=cv), where the doctor can now upload or replace their CV. The consultant "Confirm your WBA cadence" step (#12729) now lists for consultants too. | #12876, #12783, #11189 | The CV is optional at sign-up (#12783), so a doctor who skips it needs a nudge and a place to add it later. This supersedes the #9221 rule that CV is not a checklist item, which existed only because My Profile had no upload surface. Consultants now see the Cadence Tracker with MSF and 360 (#12806), so the cadence-confirm step can tick for them; saving a count through the tracker's Confirm remains the reading of OQ-OC5. |
| 2026-10-03 | "Complete your profile" now requires a payroll ID for full-platform doctors (accountAccess cpdppp or ppp). The checklist, the guard redirect and banner, the My Profile completion panel and the outstanding items all use one shared rule. CPD-only users are unaffected. | #12728 | Matt (Dev Session 2026-07-14) saw the profile tick complete while his payroll ID was blank, and Rob's 2026-07-17 decision on #10594 lists payroll ID in the required checklist. The earlier "payroll ID optional" rule (#7634 / #7656) was an engineering inference. OPEN QUESTION OQ-OC3 for Matt - whether CPD-only users are exempt is not answered; they are exempt for now because payroll ID is only used by timesheets, which are full-platform only. |
| 2026-10-03 | Task 7 spec refresh against a dated ledger of Matt's statements (GitHub, the PPP Dashboard Notion page, and meeting transcripts up to 2026-09-30). Payroll ID now gates "Complete your profile" for full-platform doctors (new AC profile-payroll-id-required, marked drift, #12728), replacing the "Payroll ID is OPTIONAL" AC. Added AC shown-to-consultants-and-non-consultants (Task 7 brief, built) and AC surgical-target-default-flagged (Matt 2026-09-21, built). Added AC cadence-confirm-step (Matt 2026-09-29, drift, #12729). Added Open Questions OQ-OC3 (CPD-only users and payroll ID), OQ-OC4 (wake time in onboarding) and OQ-OC5 (what counts as confirming the cadence). Added the dated ledger section. Status set to partial-drift. | #11189, #12728, #12729, #10594, #11144 | Async Task spec refresh, where the newest dated Matt statement wins. The "payroll optional" AC rested on an engineering inference (#7634/#7656) and on PR #10770 misquoting Rob's 2026-07-17 #10594 decision, which actually reads "incl. payroll ID". Matt's 2026-07-14 statement supersedes it. |
| 2026-10-01 | ProfileCompletionGuard's site-wide "Complete your profile" banner no longer has a dismiss control. It now shows for as long as the profile is genuinely incomplete, with no sessionStorage dismissal and no way to make it permanently disappear. | #12664 | The banner predated #12551's "No answer-once skip" rule (built for #3711, before the rule existed) and was never brought in line with it — a user who clicked its X lost the banner for the rest of the browser session even though the profile was still incomplete, the same bug class #12551 already fixed on the dashboard checklist widget. Found during a QA review video pass (2026-10-01). |
| 2026-10-01 | "Complete a wellness questionnaire" now opens inline for CPD-only doctors on CPD Home's shared OnboardingChecklist widget too, not just the full-platform PPP Dashboard's separate OnboardingSection widget. | #12673 | Found during a full Task 7 re-audit: CPD-only doctors clicking this step were navigated away to /wellness?openQuestionnaire=1, leaving the dashboard entirely — the inline interception (#7350) was only ever wired into the full-platform widget, never the shared component CPD-only doctors actually see. |
| 2026-10-01 | The "Set your appraisal date" step is now listed for full-platform doctors only (accountAccess cpdppp or ppp). CPD-only users no longer see it. A CPD-only doctor's checklist is 5 steps (6 for a surgeon) instead of 6 (7). | #12675 | The step was in the unconditional base list while its route (/appraisals/upcoming) is gated to full-platform accounts (RequirePppAccess), so a CPD-only user who clicked it was bounced back with two stacked "not available on your current plan" snackbars (Task 7 team-mode re-audit, 2026-10-01). Gated the same way as #12550's "Import your logbook" precedent. OPEN QUESTION OQ-OC2 for Matt - should CPD-only users instead see this row as an upgrade prompt to the full plan? Not built, not inferred. |
| 2026-09-29 | The remembered checklist shape now also carries the card's rendered height and the viewport width it was measured at; at the same width the placeholder reserves exactly that height (row estimate otherwise). The memory is tagged with the signed-in user (another user's memory counts as nothing remembered) and a failed status load is no longer remembered as "hidden". | #12554 | Live measurement at 375px on PR #12580 showed the row estimate under-reserving where titles and step descriptions wrap (CPD Home 96px shift, PPP Dashboard 70px); repeat-visit shift is now 0px at 1440 and 375 on both surfaces. Review minors on #12580 (shared-browser memory, failed load remembered as hidden). |
| 2026-09-28 | The "Create your first CPD plan" step now deep-links to /cpd-plans?newPlan=1 and opens the plan editor only. Both onboarding surfaces (CPD Home checklist, PPP Dashboard section) resolve the step route by step id. | #12549 | The step used /cpd-plans?add=1, and on that page add is also the open-state of the Annual Reflection dialog, so the end-of-year reflection form opened on top of the plan editor (Async Task walkthrough 2026-09-28, Task 7, #11189 at 0:32). Resolving by step id keeps the step correct when frontend and backend deploy at different times. |
| 2026-09-28 | The "Import your logbook" step is now listed for full-platform doctors only (accountAccess cpdppp or ppp). CPD-only users no longer see it. A CPD-only doctor's checklist is 6 steps (7 for a surgeon) instead of 7 (8). | #12550 | The step was in the unconditional base list (#7849, "All users") while the logbook backend rejects every CPD-only caller (#4881), so a CPD-only user who clicked it was bounced back with "This feature is not available on your current plan" (Async Task walkthrough 2026-09-28, Task 7, #11189 at 2:49). The spec did not say what a CPD-only user should see, so the step is hidden as the safe default. OPEN QUESTION OQ-OC1 for Matt - should CPD-only users instead see this row as an upgrade prompt to the full plan? Not built, not inferred; if yes it also needs a rule for the progress count, because a CPD-only user could never tick it. |
| 2026-09-28 | The checklist close button is rendered only once every step is complete, and the server rejects a dismissal while any step is open. The checklist is hidden only when it was dismissed and nothing is outstanding, so anyone who dismissed it earlier with steps still open sees it again. | #12551 | The close button was always rendered and the widget hid on the dismissal timestamp alone, so a CPD-only consultant with 3 of 7 steps open had no checklist and no way to restore it (Async Task walkthrough 2026-09-28, Task 7, #11189 at 3:02). This aligns the build with the existing spec wording - the close is for once everything is genuinely complete - without adding a separate restore control, which the spec rules out (#8027). |
| 2026-09-28 | Both checklist surfaces (PPP Dashboard "Outstanding Onboarding" section, CPD Home "Getting Started" widget) reserve the checklist's space with a skeleton placeholder while onboarding.getStatus loads, sized from the shape this browser last saw (shown/hidden + step count, localStorage per surface; a hidden checklist reserves nothing). The status query opts out of the page's request batch (skipBatch) so it no longer waits on the slowest sibling procedure. | #12554 | The card arrived late and pushed the page down (Async Task walkthrough 2026-09-28, Task 7, #11189 at 0:17); the CPD Home widget showed a fixed 200px block for 4-5 s that neither matched the card nor stayed when the checklist was hidden. Measured on UAT the status sat inside a 12-procedure, 106 KB dashboard batch (626 ms even on a fast link), and a tRPC batch resolves only when its slowest member has. |
| 2026-07-17 | Default Working-Calendar Start (jobContractStartDate) becomes a base requirement for the "Complete your profile" step, alongside regulatory body and registration number, on every profile-completion surface (checklist, guard redirect, My Profile completion panel, outstanding-items banner). The My Profile form now pre-populates the picker with 1 February (AU default) instead of leaving it blank. Payroll ID stays OPTIONAL — unchanged. | #10594 | Matt's profile showed a completed-profile tick while payroll ID was unset and the working-year-start picker was blank with no default populated. Rob asked for a defined, spec'd checklist of required fields that gates the tick rather than an ad-hoc check. Rob's follow-up decision (2026-07-17) confirmed payroll ID stays optional per the prior #7634/#7656/#7348/#7358 decision — only the working-calendar-start field is newly required. |
| 2026-07-09 | Import your logbook checklist step becomes tri-state (not started / partially complete with an outstanding-count note / complete) instead of a flat boolean. | #10130 | The import wizard itself never blocked on unresolved near-matches (#8467/#8443), but the checklist step could still read as fully done while imported cases had unresolved procedure/hospital matches. Matt & Rob agreed the import should proceed and the checklist should read "partially complete" with a count of what's left, not silently claim done. |
| 2026-06-29 | Remove CV/resume from the onboarding checklist profile-completion gate and outstanding-items list. | #9221 | The CV upload was removed from My Profile (#9202); the checklist item linked to /my-profile where no CV upload UI exists. CV is captured at sign-up and managed in the PPP Passport (#9196). |
| 2026-06-24 | Update "Connect your data" step route from /wellness?tab=data-sources (404'd) to /wellness/settings (the canonical Data Sources surface). | #9254 | The route /wellness?tab=data-sources had no registered handler and sent users to a 404. The canonical surface is /wellness/settings. A /wellness/data-sources redirect alias is also registered for native-app deep links. |
| 2026-06-22 | Added a core @smoke scenario for the Getting Started checklist auto-hide behaviour in onboarding.feature. | #9068, #9055 | SGD C4 drift — the built Onboarding Checklist spec lacked a name-matched core smoke scenario despite extensive existing checklist coverage in onboarding.feature. |
| 2026-06-20 | "Set your appraisal date" step uses ?openAnnualForm=1 instead of ?add=1; "Log your first CPD activity" step uses URLSearchParams for from param to avoid double-encoding. | #8983, #8946, #8947, #8948 | #8948 — ?add=1 on the appraisals route opens MCR/360/MSF request modals, not the annual appraisal form; ?openAnnualForm=1 is the correct param. #8946/#8947 — naive string concatenation on wizard navigation URLs that already had a query string double-encoded the from param (e.g. from=wizard%3Ffrom%3Donboarding), breaking the return-to-dashboard flow after saving a CPD activity. |
| 2026-06-20 | Correct the Smart GeoTag onboarding step route from /profile#hospitals to /my-profile#hospitals. | #8953, #8945 | #8945 — the documented /profile route never existed in the router, so the CTA navigated nowhere; the step now points at the real /my-profile#hospitals hospital-linking deep link, matching dashboard.md. |
| 2026-06-02 | New spec — the dashboard Getting Started checklist split out of onboarding.md into its own SGD feature (feature:onboarding-checklist), with the #8027 mechanism, steps, no-skip, visibility and superseded-wizard ACs moved here. | #8082, #8077, #8027 | After #8027 removed the Phase 2 Setup Wizard, the dashboard checklist is the surviving, central onboarding surface and warranted a 1:1 label↔spec of its own. Cadence model + sign-up stay in onboarding.md. |