---

name: onboarding-upgrade-prompt-when-credits-low
description: 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.
license: MIT
metadata:
id: onboarding.upgrade-prompt-when-credits-low
category: onboarding
priority: P0
intent: [upgrade, credits, upsell, onboarding, tier-restriction]
related: [unlock-contextual-upsell, onboarding-first-session-checklist, ops-credit-burn-rate-watcher, ops-churn-risk-detector]
source: Louis — HAQQ Legal AI (github.com/sboghossian/mini-claude-for-legal)
version: "1.0"

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:

1. Credit depletion threshold — the user has consumed ≥ 80% of their monthly token/credit allowance (i.e., fewer than 20% of credits remain).
2. 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).
3. 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