SaaS Onboarding Journey Spec Skill
Use When
- Use when specifying a SaaS aha event, activation milestones, segmented paths, nudges, measurement sources, and drop-off interventions. Use customer-success-playbook for ongoing intervention and user-manual for product procedures.
Do Not Use When
- Do not use when there is no signup flow.
- Do not use this skill to fabricate missing project facts, legal conclusions, test results, approvals, or certification claims.
Required Inputs
| Artefact |
Source or provider |
Required? |
Missing-input behaviour |
| Target sources: PRD.md, Pricing_And_Packaging_Spec.md, user-research notes, product-analytics access (events catalogue). |
Project owner, approved workspace artefacts, or accountable control owner |
Yes |
Stop dependent claims; list the missing item, owner, and consequence. For review checks, record not assessed. |
| Scope, audience, baseline/version, and accountable decision owner |
Requester or project context |
Yes |
Ask for or record the gap; do not infer authority or scope. |
Capability and permission boundaries
Default to read-only. Read and search access to the supplied artefacts are required. Editing is limited to an explicitly authorised requested draft or project files. Execute validation only when authorised; publishing, signature, certification, production mutation, destructive action, spending, and risk acceptance require explicit authority.
Degraded Mode
When files, tools, network, rendering, fonts, execution, or evidence are unavailable, return the narrowest useful qualified draft or finding set. Name every unavailable check and its consequence; an unassessed check is never a pass. Preserve evidence already gathered and provide the exact next verification step.
Decision Rules
| Condition |
Action |
Failure or risk avoided |
| A claim, segment, trigger, metric, or intervention lacks product evidence |
Qualify it and request the missing source |
Generic playbooks detached from product reality |
| Consent, suppression, fairness, or customer-harm guardrail fails |
Stop the affected play or campaign |
Dark patterns or non-compliant outreach |
Workflow
- Confirm the requested artefact, audience, scope, decision owner, and applicable baseline or version. Work read-only by default; source mutation, publication, signature, certification, production change, or risk acceptance requires explicit authority.
- Inspect every required input and record missing, stale, conflicting, or inaccessible evidence. Stop claims that depend on an unresolved required input.
- Apply the Decision Rules, then execute the existing Core Instructions below in order; preserve project terminology and trace each material statement to its source.
- Test the draft against the output acceptance conditions and domain quality standards. If a check cannot run, mark it
not assessed and never convert it into a pass.
- On failure, recover by preserving completed evidence, identifying the narrowest corrective action and owner, and rerunning only the affected checks before handoff.
- Produce the named artefact and evidence record; publish, sign, certify, mutate production, or accept risk only under explicit authority.
Outputs
| Artefact |
Consumer |
Observable acceptance condition |
| SaaS Onboarding Journey Spec |
Customer, support, success, sales, or implementation owner |
Aha-moment is a single named event. Every milestone has a target completion window and a measurement source. Every nudge has a channel and a trigger. |
| Gap and decision record |
Accountable owner and downstream reviewer |
Every gap has status, impact, owner, next action, and no unsupported pass or approval. |
Evidence Produced
| Evidence |
Contents |
Acceptance condition |
| SaaS Onboarding Journey Spec evidence record |
Source identifiers, scope/version, decisions, checks, exceptions, and approval state |
A reviewer can reproduce each material conclusion from named sources. |
| Validation record |
Check, result (pass, fail, or not assessed), evidence location, date, and actor |
No required check is omitted or silently treated as passed. |
Quality Standards
- Aha-moment is a single named event. Every milestone has a target completion window and a measurement source. Every nudge has a channel and a trigger.
- Use deterministic acceptance conditions and preserve traceability from source to decision and output.
- Separate facts, inferences, assumptions, and approvals; never present one as another.
- Apply
28-anti-ai-slop during authoring and 29-ai-slop-audit at major checkpoints and release.
Anti-Patterns
- Producing SaaS Onboarding Journey Spec from assumptions instead of named project sources. Fix: Cite the source or mark the item unverified.
- Treating a missing or inaccessible check as passed. Fix: Mark it
not assessed, state impact, and block dependent claims.
- Using vague gates such as
adequate, secure, or user-friendly. Fix: Replace each with an observable criterion, threshold, and evidence source.
- Copying a generic template without product, control, role, version, or jurisdiction detail. Fix: Ground every section in the supplied context and remove unused boilerplate.
- Publishing, signing, certifying, changing production, or accepting risk without authority. Fix: Prepare a draft and route the decision to the accountable owner.
- Listing evidence without provenance or an acceptance result. Fix: Record source, period, integrity check, mapping, and pass/fail/not-assessed status.
Worked Example
Example: if a claim, segment, trigger, metric, or intervention lacks product evidence, qualify it and request the missing source. Record the evidence and result in the validation record; this avoids generic playbooks detached from product reality.
References
- Generation logic: load when creating the complete artefact.
- Skill notes: consult for local examples and invocation context.
- Repository operating rules: apply the engine's routing, evidence, and release gates.
First-value and friction controls
The aha event is the first meaningful outcome, not account creation or profile
completion. Make nonessential fields, permissions, invitations, and education
progressive and deferrable; prefer learn-by-doing and contextual guidance over
a mandatory tour. Every path needs skip/dismiss, resume, recovery, and a route
for returning users. If identity, consent, or verification is a genuine
prerequisite, explain the purpose and consequence, minimise the step, and name
support/recovery rather than bypassing the control.
Replace fixed KPI defaults with product-specific baselines and predeclared
thresholds. The event catalogue must distinguish signup, first value, repeated
value, and retention; it must not imply activation merely because a user
registered. Validate the journey with representative users and inspect
drop-off, task success, support questions, accessibility, and guardrails.
Practitioner cross-check: Eleken mobile onboarding guide; platform corroboration: Apple onboarding guidance.
Overview
Sourced from Garbugli (lifecycle email) and Walling (activation as escape-velocity threshold). Produces the explicit onboarding-journey doc many SaaS lack.
Core Instructions
Step 1: Define the aha-moment
A single named product event where the user first perceives value. State it precisely (e.g. "first invoice sent", "first deal closed in pipeline", "first dashboard published"). Activation rate = % of signups reaching this event within N days.
Step 2: Define activation milestones
| # |
Milestone |
Event name |
Target window |
Why it matters |
| 1 |
Sign-up complete |
user.signed_up |
T0 |
enter funnel |
| 2 |
Profile complete |
user.profile_completed |
T+5 min |
reduces friction |
| 3 |
First action |
<product-specific> |
T+1 day |
hands-on engagement |
| 4 |
Aha moment |
<aha event> |
T+7 day |
core activation |
| 5 |
Team invited / integration |
team.invited or integration.connected |
T+14 day |
stickiness |
| 6 |
Habit formed |
user.returned_3_times in 7 d |
T+21 day |
retention indicator |
Step 3: Channel orchestration
For each milestone, define the nudge program if the milestone hasn't fired:
| Stage |
In-app |
Email |
Push |
SMS |
CSM (Gold/Ent) |
| Sign-up |
welcome modal |
welcome email |
– |
– |
– |
| 24h no profile |
tooltip |
reminder |
– |
– |
– |
| Day 3 no first action |
guided tour |
activation tip |
– |
– |
– |
| Day 7 no aha |
targeted offer / on-screen template |
aha-moment story |
– |
– |
call (Gold) |
| Day 14 no team |
invite prompt |
team-onboarding playbook |
– |
– |
– |
Max 3 touches per day per user.
Step 4: Drop-off interventions
For each commonly-dropped step, design an intervention (in-product flow, CSM call, integration concierge, refund-trial-extend offer).
Step 5: KPI thresholds
| Metric |
Target |
Owner |
| Sign-up → activation |
≥ 30% |
Product + Growth |
| Time-to-aha P50 |
≤ 5 days |
Product |
| Day-30 retention of activated cohort |
≥ 60% |
Product + CS |
| Email open rate (onboarding) |
≥ 40% |
Lifecycle |
| In-app nudge click-through |
≥ 25% |
Growth |
Step 6: Segmented paths
Per ICP and per tier. Enterprise has CSM-led onboarding overlay; SMB is product-led; freelance is fully self-serve. Document the differences.
Step 7: Write the spec
Onboarding_Journey_Spec.md with sections: 1) Aha-Moment, 2) Activation Milestones, 3) Channel Orchestration, 4) Drop-off Interventions, 5) KPI Thresholds, 6) Segmented Paths, 7) Event Catalogue (events emitted at each milestone), 8) Review cadence.
Standards
- ISO 26514 (user documentation).
- IEEE 29148 (stakeholder requirements).
- Garbugli (SaaS Email Marketing Playbook).
Resources
logic.prompt, README.md, references/saas-onboarding-journey-spec-template.md.
1---2name: 06-saas-onboarding-journey-spec3description: Use when specifying a SaaS aha event, activation milestones, segmented paths, nudges, measurement sources, and drop-off interventions. Use customer-success-playbook for ongoing intervention and user-manual for product procedures.4---56# SaaS Onboarding Journey Spec Skill78<!-- dual-compat-start -->910## Use When1112- Use when specifying a SaaS aha event, activation milestones, segmented paths, nudges, measurement sources, and drop-off interventions. Use customer-success-playbook for ongoing intervention and user-manual for product procedures.1314## Do Not Use When1516- Do not use when there is no signup flow.17- Do not use this skill to fabricate missing project facts, legal conclusions, test results, approvals, or certification claims.1819## Required Inputs2021| Artefact | Source or provider | Required? | Missing-input behaviour |22|---|---|---:|---|23| Target sources: PRD.md, Pricing_And_Packaging_Spec.md, user-research notes, product-analytics access (events catalogue). | Project owner, approved workspace artefacts, or accountable control owner | Yes | Stop dependent claims; list the missing item, owner, and consequence. For review checks, record `not assessed`. |24| Scope, audience, baseline/version, and accountable decision owner | Requester or project context | Yes | Ask for or record the gap; do not infer authority or scope. |2526## Capability and permission boundaries2728Default to read-only. Read and search access to the supplied artefacts are required. Editing is limited to an explicitly authorised requested draft or project files. Execute validation only when authorised; publishing, signature, certification, production mutation, destructive action, spending, and risk acceptance require explicit authority.2930## Degraded Mode3132When files, tools, network, rendering, fonts, execution, or evidence are unavailable, return the narrowest useful qualified draft or finding set. Name every unavailable check and its consequence; an unassessed check is never a pass. Preserve evidence already gathered and provide the exact next verification step.3334## Decision Rules3536| Condition | Action | Failure or risk avoided |37|---|---|---|38| A claim, segment, trigger, metric, or intervention lacks product evidence | Qualify it and request the missing source | Generic playbooks detached from product reality |39| Consent, suppression, fairness, or customer-harm guardrail fails | Stop the affected play or campaign | Dark patterns or non-compliant outreach |4041## Workflow42431. Confirm the requested artefact, audience, scope, decision owner, and applicable baseline or version. Work read-only by default; source mutation, publication, signature, certification, production change, or risk acceptance requires explicit authority.442. Inspect every required input and record missing, stale, conflicting, or inaccessible evidence. Stop claims that depend on an unresolved required input.453. Apply the Decision Rules, then execute the existing Core Instructions below in order; preserve project terminology and trace each material statement to its source.464. Test the draft against the output acceptance conditions and domain quality standards. If a check cannot run, mark it `not assessed` and never convert it into a pass.475. On failure, recover by preserving completed evidence, identifying the narrowest corrective action and owner, and rerunning only the affected checks before handoff.486. Produce the named artefact and evidence record; publish, sign, certify, mutate production, or accept risk only under explicit authority.4950## Outputs5152| Artefact | Consumer | Observable acceptance condition |53|---|---|---|54| SaaS Onboarding Journey Spec | Customer, support, success, sales, or implementation owner | Aha-moment is a single named event. Every milestone has a target completion window and a measurement source. Every nudge has a channel and a trigger. |55| Gap and decision record | Accountable owner and downstream reviewer | Every gap has status, impact, owner, next action, and no unsupported pass or approval. |5657## Evidence Produced5859| Evidence | Contents | Acceptance condition |60|---|---|---|61| SaaS Onboarding Journey Spec evidence record | Source identifiers, scope/version, decisions, checks, exceptions, and approval state | A reviewer can reproduce each material conclusion from named sources. |62| Validation record | Check, result (`pass`, `fail`, or `not assessed`), evidence location, date, and actor | No required check is omitted or silently treated as passed. |6364## Quality Standards6566- Aha-moment is a single named event. Every milestone has a target completion window and a measurement source. Every nudge has a channel and a trigger.67- Use deterministic acceptance conditions and preserve traceability from source to decision and output.68- Separate facts, inferences, assumptions, and approvals; never present one as another.69- Apply `28-anti-ai-slop` during authoring and `29-ai-slop-audit` at major checkpoints and release.7071## Anti-Patterns7273- **Producing SaaS Onboarding Journey Spec from assumptions instead of named project sources.** Fix: Cite the source or mark the item unverified.74- **Treating a missing or inaccessible check as passed.** Fix: Mark it `not assessed`, state impact, and block dependent claims.75- **Using vague gates such as `adequate`, `secure`, or `user-friendly`.** Fix: Replace each with an observable criterion, threshold, and evidence source.76- **Copying a generic template without product, control, role, version, or jurisdiction detail.** Fix: Ground every section in the supplied context and remove unused boilerplate.77- **Publishing, signing, certifying, changing production, or accepting risk without authority.** Fix: Prepare a draft and route the decision to the accountable owner.78- **Listing evidence without provenance or an acceptance result.** Fix: Record source, period, integrity check, mapping, and pass/fail/not-assessed status.7980## Worked Example8182Example: if a claim, segment, trigger, metric, or intervention lacks product evidence, qualify it and request the missing source. Record the evidence and result in the validation record; this avoids generic playbooks detached from product reality.8384## References8586- [Generation logic](logic.prompt): load when creating the complete artefact.87- [Skill notes](README.md): consult for local examples and invocation context.88- [Repository operating rules](../../AGENTS.md): apply the engine's routing, evidence, and release gates.8990## First-value and friction controls9192The aha event is the first meaningful outcome, not account creation or profile93completion. Make nonessential fields, permissions, invitations, and education94progressive and deferrable; prefer learn-by-doing and contextual guidance over95a mandatory tour. Every path needs skip/dismiss, resume, recovery, and a route96for returning users. If identity, consent, or verification is a genuine97prerequisite, explain the purpose and consequence, minimise the step, and name98support/recovery rather than bypassing the control.99100Replace fixed KPI defaults with product-specific baselines and predeclared101thresholds. The event catalogue must distinguish signup, first value, repeated102value, and retention; it must not imply activation merely because a user103registered. Validate the journey with representative users and inspect104drop-off, task success, support questions, accessibility, and guardrails.105106Practitioner cross-check: [Eleken mobile onboarding guide](https://www.eleken.co/blog-posts/mobile-app-onboarding-best-practices); platform corroboration: [Apple onboarding guidance](https://developer.apple.com/design/human-interface-guidelines/onboarding).107108<!-- dual-compat-end -->109110## Overview111112Sourced from Garbugli (lifecycle email) and Walling (activation as escape-velocity threshold). Produces the explicit onboarding-journey doc many SaaS lack.113114## Core Instructions115116### Step 1: Define the aha-moment117118A single named product event where the user first perceives value. State it precisely (e.g. "first invoice sent", "first deal closed in pipeline", "first dashboard published"). Activation rate = % of signups reaching this event within N days.119120### Step 2: Define activation milestones121122| # | Milestone | Event name | Target window | Why it matters |123|---|-----------|------------|---------------|----------------|124| 1 | Sign-up complete | `user.signed_up` | T0 | enter funnel |125| 2 | Profile complete | `user.profile_completed` | T+5 min | reduces friction |126| 3 | First action | `<product-specific>` | T+1 day | hands-on engagement |127| 4 | Aha moment | `<aha event>` | T+7 day | core activation |128| 5 | Team invited / integration | `team.invited` or `integration.connected` | T+14 day | stickiness |129| 6 | Habit formed | `user.returned_3_times` in 7 d | T+21 day | retention indicator |130131### Step 3: Channel orchestration132133For each milestone, define the nudge program if the milestone hasn't fired:134135| Stage | In-app | Email | Push | SMS | CSM (Gold/Ent) |136|-------|--------|-------|------|-----|----------------|137| Sign-up | welcome modal | welcome email | – | – | – |138| 24h no profile | tooltip | reminder | – | – | – |139| Day 3 no first action | guided tour | activation tip | – | – | – |140| Day 7 no aha | targeted offer / on-screen template | aha-moment story | – | – | call (Gold) |141| Day 14 no team | invite prompt | team-onboarding playbook | – | – | – |142143Max 3 touches per day per user.144145### Step 4: Drop-off interventions146147For each commonly-dropped step, design an intervention (in-product flow, CSM call, integration concierge, refund-trial-extend offer).148149### Step 5: KPI thresholds150151| Metric | Target | Owner |152|--------|--------|-------|153| Sign-up → activation | ≥ 30% | Product + Growth |154| Time-to-aha P50 | ≤ 5 days | Product |155| Day-30 retention of activated cohort | ≥ 60% | Product + CS |156| Email open rate (onboarding) | ≥ 40% | Lifecycle |157| In-app nudge click-through | ≥ 25% | Growth |158159### Step 6: Segmented paths160161Per ICP and per tier. Enterprise has CSM-led onboarding overlay; SMB is product-led; freelance is fully self-serve. Document the differences.162163### Step 7: Write the spec164165`Onboarding_Journey_Spec.md` with sections: 1) Aha-Moment, 2) Activation Milestones, 3) Channel Orchestration, 4) Drop-off Interventions, 5) KPI Thresholds, 6) Segmented Paths, 7) Event Catalogue (events emitted at each milestone), 8) Review cadence.166167## Standards168169- ISO 26514 (user documentation).170- IEEE 29148 (stakeholder requirements).171- Garbugli (SaaS Email Marketing Playbook).172173## Resources174175- `logic.prompt`, `README.md`, `references/saas-onboarding-journey-spec-template.md`.
peterbamuhigire