Onboarding — Upgrade Prompt When Credits Low
When this applies
This skill governs every in-product moment where the system needs to surface an upgrade or plan-expansion prompt. It activates on three distinct triggers:
- Credit depletion threshold — the user has consumed ≥ 80% of their monthly token/credit allowance (i.e., fewer than 20% of credits remain).
- Tier-restricted feature block — the user attempts to invoke a feature that requires a higher plan (e.g., Deep Research, multi-jurisdiction analysis, bulk drafting, document workspace beyond the free limit).
- Heavy-use day — intraday usage is ≥ 3× the user's own rolling daily average, signalling an imminent exhaustion event even if the monthly counter has not yet triggered.
Behavior
Credit-low prompt
When the 80% threshold is reached, surface a non-blocking, dismissable prompt at the next natural break (after the assistant has finished delivering a response — never mid-generation):
You've used 80% of your monthly credits. Upgrade to Pro for 50,000 more credits, or wait until your next reset on [date].
[Upgrade now] [Remind me in 7 days] [Don't show again this cycle]
- "Upgrade now" → deep-link to the billing/plan page with the correct plan pre-selected.
- "Remind me in 7 days" → suppresses the prompt for 7 days unless the user hits 95%.
- "Don't show again this cycle" → suppresses until the monthly reset (and never again for this cycle).
At 95% depletion, re-surface regardless of the 7-day suppression — the user may be about to lose access mid-matter, which is a real harm.
Tier-restricted feature prompt
When the user attempts a feature outside their tier, replace the blocked action with:
[Feature name] is available on Pro and above. You can:
[See plans →] [Try once for X credits] [Go back]
- "Try once for X credits" is only shown if the user has sufficient credits remaining — never show it if credits would go negative.
- Do not expose the underlying technical reason for the block (e.g., don't say "feature flag disabled for free tier").
Heavy-use day prompt
When intraday burn hits 3× the daily average, surface a soft heads-up — not an upgrade push:
You're using Louis heavily today. At this pace, your credits may run out before your [date] reset. Upgrade to avoid interruptions.
[Upgrade] [Dismiss]
Timing rules
| Rule |
Details |
| Not during distress |
If the conversation signals emotional weight (grief, crisis, urgent matter, high-stakes client situation), defer all upgrade prompts by 24 hours. |
| Not mid-task |
Only surface after the assistant has delivered a complete response — never interrupt a streaming reply. |
| Frequency cap |
At most one upgrade prompt per 24-hour window per user. Multiple triggers on the same day queue to the next break, they do not stack. |
| Dismissal respected |
"Don't show again" is honoured until the next billing cycle reset. Suppression state is stored server-side, not only in the browser. |
| Post-success timing |
Ideal placement is immediately after a high-value output (a completed draft, a research summary). The user has just experienced value — the upsell has more credibility here. |
Copy principles
- Show real value first. The prompt appears after the user has already received something useful. Reference that: "You've drafted 12 contracts this month — keep the momentum going."
- Be specific about what they get. "50,000 more credits" is better than "more credits". "Unlimited document workspace" is better than "more features".
- One primary action. Every prompt has a single prominent CTA. Secondary options (Remind me later, Dismiss) are clearly secondary in the visual hierarchy.
- No manufactured urgency. Do not use countdown timers or "limited time" language unless it is factually true.
Edge cases
- Trial-tier users: surface the prompt at 60% (not 80%) because trials often have lower absolute credit ceilings.
- Enterprise accounts: suppress all credit prompts — billing is handled outside the product. Show usage dashboards instead via the admin panel.
- BYO-key users (bring-your-own API key): suppress the credit-based prompts entirely. Show a warning only if their configured API key returns quota errors from the upstream provider.
- Concurrent sessions: token consumption is aggregated at the user/tenant level, not per session. Ensure the credit counter reflects the true aggregate.
Do not
- Do not push upgrade prompts inside emotionally sensitive legal contexts (divorce proceedings, criminal matters, bereavement estate work).
- Do not use guilt framing ("You're about to lose everything you've built…").
- Do not surface upgrade prompts more than once per 24 hours.
- Do not block a user mid-generation — always let the current response complete.
- Do not fabricate credit figures or reset dates — pull live values from the billing service.
Related skills
- [[unlock-contextual-upsell]] — for upselling within the flow of substantive legal work
- [[onboarding-first-session-checklist]] — the broader onboarding sequence this fits into
- [[ops-credit-burn-rate-watcher]] — the backend monitor that feeds the trigger signals
- [[ops-churn-risk-detector]] — detects when heavy usage coupled with upgrade refusal signals churn risk
1---2name: onboarding-upgrade-prompt-when-credits-low3description: Use when a user is approaching or has hit their credit/token limit, attempts a tier-restricted feature, or shows a high-burn usage pattern. Governs the exact timing, copy, and frequency rules for surfacing upgrade prompts inside a legal AI chat product — including hard rules about deferral during emotionally sensitive conversations and mid-task interruptions.4license: MIT5---67# Onboarding — Upgrade Prompt When Credits Low89## When this applies1011This skill governs every in-product moment where the system needs to surface an upgrade or plan-expansion prompt. It activates on three distinct triggers:12131. **Credit depletion threshold** — the user has consumed ≥ 80% of their monthly token/credit allowance (i.e., fewer than 20% of credits remain).142. **Tier-restricted feature block** — the user attempts to invoke a feature that requires a higher plan (e.g., Deep Research, multi-jurisdiction analysis, bulk drafting, document workspace beyond the free limit).153. **Heavy-use day** — intraday usage is ≥ 3× the user's own rolling daily average, signalling an imminent exhaustion event even if the monthly counter has not yet triggered.1617## Behavior1819### Credit-low prompt2021When the 80% threshold is reached, surface a non-blocking, dismissable prompt at the next natural break (after the assistant has finished delivering a response — never mid-generation):2223> You've used 80% of your monthly credits. Upgrade to Pro for 50,000 more credits, or wait until your next reset on [date].24>25> [**Upgrade now**] [Remind me in 7 days] [Don't show again this cycle]2627- "Upgrade now" → deep-link to the billing/plan page with the correct plan pre-selected.28- "Remind me in 7 days" → suppresses the prompt for 7 days unless the user hits 95%.29- "Don't show again this cycle" → suppresses until the monthly reset (and never again for this cycle).3031At **95% depletion**, re-surface regardless of the 7-day suppression — the user may be about to lose access mid-matter, which is a real harm.3233### Tier-restricted feature prompt3435When the user attempts a feature outside their tier, replace the blocked action with:3637> **[Feature name]** is available on Pro and above. You can:38>39> [**See plans →**] [**Try once for X credits**] [Go back]4041- "Try once for X credits" is only shown if the user has sufficient credits remaining — never show it if credits would go negative.42- Do not expose the underlying technical reason for the block (e.g., don't say "feature flag disabled for free tier").4344### Heavy-use day prompt4546When intraday burn hits 3× the daily average, surface a soft heads-up — not an upgrade push:4748> You're using Louis heavily today. At this pace, your credits may run out before your [date] reset. Upgrade to avoid interruptions.49>50> [**Upgrade**] [Dismiss]5152## Timing rules5354| Rule | Details |55|------|---------|56| Not during distress | If the conversation signals emotional weight (grief, crisis, urgent matter, high-stakes client situation), defer all upgrade prompts by 24 hours. |57| Not mid-task | Only surface after the assistant has delivered a complete response — never interrupt a streaming reply. |58| Frequency cap | At most one upgrade prompt per 24-hour window per user. Multiple triggers on the same day queue to the next break, they do not stack. |59| Dismissal respected | "Don't show again" is honoured until the next billing cycle reset. Suppression state is stored server-side, not only in the browser. |60| Post-success timing | Ideal placement is immediately after a high-value output (a completed draft, a research summary). The user has just experienced value — the upsell has more credibility here. |6162## Copy principles6364- **Show real value first.** The prompt appears after the user has already received something useful. Reference that: "You've drafted 12 contracts this month — keep the momentum going."65- **Be specific about what they get.** "50,000 more credits" is better than "more credits". "Unlimited document workspace" is better than "more features".66- **One primary action.** Every prompt has a single prominent CTA. Secondary options (Remind me later, Dismiss) are clearly secondary in the visual hierarchy.67- **No manufactured urgency.** Do not use countdown timers or "limited time" language unless it is factually true.6869## Edge cases7071- **Trial-tier users**: surface the prompt at 60% (not 80%) because trials often have lower absolute credit ceilings.72- **Enterprise accounts**: suppress all credit prompts — billing is handled outside the product. Show usage dashboards instead via the admin panel.73- **BYO-key users** (bring-your-own API key): suppress the credit-based prompts entirely. Show a warning only if their configured API key returns quota errors from the upstream provider.74- **Concurrent sessions**: token consumption is aggregated at the user/tenant level, not per session. Ensure the credit counter reflects the true aggregate.7576## Do not7778- Do not push upgrade prompts inside emotionally sensitive legal contexts (divorce proceedings, criminal matters, bereavement estate work).79- Do not use guilt framing ("You're about to lose everything you've built…").80- Do not surface upgrade prompts more than once per 24 hours.81- Do not block a user mid-generation — always let the current response complete.82- Do not fabricate credit figures or reset dates — pull live values from the billing service.8384## Related skills8586- [[unlock-contextual-upsell]] — for upselling within the flow of substantive legal work87- [[onboarding-first-session-checklist]] — the broader onboarding sequence this fits into88- [[ops-credit-burn-rate-watcher]] — the backend monitor that feeds the trigger signals89- [[ops-churn-risk-detector]] — detects when heavy usage coupled with upgrade refusal signals churn risk
sboghossian