Skip to main content

​
05 — Pre-Operation Confirmation System

Ring: 1 (Launch Blocker) Dependency: R1-2 (Cost Control — cost info needed), R1-4 (Billing — plan/limit info needed) Handbook: Ch. 76 (credit costs), Ch. 6 (WOW moment — minimize friction but keep costs transparent)

​
Problem

  • AI operations cost money but the user is unaware.
  • Limit overages happen silently (currently there are no limits at all).
  • User clicks “Discovery” but doesn’t know it costs 1 credit / 1 quota.
  • A misclick could burn through 50 discovery quotas in 2 minutes.

​
Decisions

​
D1: Confirmation Dialog on Every Costly Operation

User clicks "Discover" / "Headhunt" / "Enrich"
  → Frontend: calls /api/usage/check
  → Backend: checks plan limit + credit balance
  → Frontend: shows UsageConfirmDialog
  → User clicks "Confirm" → operation starts
  → User clicks "Cancel" → operation aborted

​
D2: Dialog Content by Plan Type

Free Plan: 
┌─────────────────────────────────────────┐
│  Discover Companies                     │
│                                         │
│  This operation will use 1 quota from   │
│  your monthly search limit.             │
│                                         │
│  Remaining: 2 / 3                       │
│  ████████░░░░ 67% used                  │
│                                         │
│  [ ] Don't ask again this session       │
│                                         │
│  [Cancel]              [Confirm]        │
└─────────────────────────────────────────┘
Pro Plan (within limit): 
┌─────────────────────────────────────────┐
│  Discover Companies                     │
│                                         │
│  This operation will use 1 quota from   │
│  your monthly search limit.             │
│                                         │
│  Remaining: 38 / 50                     │
│  ██████░░░░░░ 24% used                  │
│                                         │
│  [ ] Don't ask again this session       │
│                                         │
│  [Cancel]              [Confirm]        │
└─────────────────────────────────────────┘
Pro Plan (over limit — credit usage): 
┌─────────────────────────────────────────┐
│  Discover Companies                     │
│                                         │
│  ⚠ Your monthly limit is reached.      │
│  This operation will cost 1 credit.     │
│                                         │
│  Credit balance: 23                     │
│  After operation: 22                    │
│                                         │
│  [ ] Don't ask again this session       │
│                                         │
│  [Buy Credits]  [Cancel]  [Confirm]     │
└─────────────────────────────────────────┘
Limit + credits exhausted: 
┌─────────────────────────────────────────┐
│  Discover Companies                     │
│                                         │
│  ❌ Monthly limit and credits are       │
│     exhausted.                          │
│                                         │
│  [Buy Credits]  [Upgrade Plan]          │
└─────────────────────────────────────────┘
Enterprise (informational mode — can be turned off in settings): 
┌─────────────────────────────────────────┐
│  Discover Companies                     │
│                                         │
│  This month: 142 searches performed     │
│  ℹ Unlimited plan — no limits           │
│                                         │
│  [ ] Don't ask again this session       │
│                                         │
│  [Confirm]                              │
└─────────────────────────────────────────┘

​
D3: Bypass Rules

RuleDescription
DefaultDialog is shown on EVERY costly operation
”Don’t ask again this session”Session-based (sessionStorage). Resets when the browser is closed. Per operation type — disabling for discovery does not affect headhunt.
Enterprise disableusage_confirmation: false in org settings. Only visible in the Enterprise plan. Dialog is completely disabled, operations start immediately.
Limit approachingWhen remaining quota is <= 20%, the dialog is shown EVEN IF “don’t ask” is selected (warning purpose).

​
D4: Which Operations Trigger the Dialog

OperationDialogReason
Discovery✅1 quota / 1 credit
Headhunt✅1 quota / 1 credit
Deep enrichment✅2 credits
Batch operation✅N * 0.5 credits (total shown)
Score recalculate❌Deterministic, no AI cost
Lead CRUD❌DB operation, no cost
Company list/filter❌DB query, no cost
Scraper file upload✅AI classify cost applies

​
Architecture

​
Component

components/UsageConfirmDialog.tsx
  Props:
    action: 'discovery' | 'headhunt' | 'enrichment' | 'batch' | 'scraper'
    onConfirm: () => void
    onCancel: () => void

  Internal flow:
    1. On mount, call /api/usage/check?action=X
    2. Build dialog content based on response
    3. "Don't ask again" → write to sessionStorage
    4. Confirm → call onConfirm()
    5. Cancel → call onCancel()

  sessionStorage key: `usage_confirm_skip_$\{action\}`

​
API

GET /api/usage/check?action=discovery
Response:
{
  "allowed": true,
  "source": "plan_limit",          // 'plan_limit' | 'credit' | 'unlimited'
  "remaining": 38,
  "limit": 50,
  "usedPercent": 24,
  "creditCost": null,              // null = within plan
  "creditBalance": 23,
  "plan": "pro",
  "canBypassDialog": false         // Enterprise + settings off
}

​
Current Code Impact

​
New Files

FileContent
components/UsageConfirmDialog.tsxConfirmation dialog component
lib/hooks/useUsageCheck.tsHook: call /api/usage/check + sessionStorage check

​
Files to Change

FileChange
app/discovery/page.tsx”Discover” button → wrap with UsageConfirmDialog
app/companies/hooks/useCompanyData.tsHeadhunt → wrap with UsageConfirmDialog
app/companies/components/CompanyDetailModal.tsxHeadhunt button → UsageConfirmDialog
app/scraper/page.tsxPush/classify → UsageConfirmDialog

​
Atomic Tasks

#TaskRingSize
CONFIRM-1GET /api/usage/check endpoint (together with 04-billing check-usage)R1Medium
CONFIRM-2components/UsageConfirmDialog.tsx — 4 variants (plan/credit/exhausted/enterprise)R1Medium
CONFIRM-3lib/hooks/useUsageCheck.ts — hook + sessionStorage bypassR1Small
CONFIRM-4Discovery page integrationR1Small
CONFIRM-5Headhunt integration (companies page + modal)R1Small
CONFIRM-6Scraper integrationR1Small
CONFIRM-7Batch operations integration (with 06)R2Small
CONFIRM-8Enterprise org settings → “usage_confirmation: false”R1Small