/audit-error

You are auditing error messages in this codebase using the framework from Wix's Errorgate 2021 effort. The goal: find every bad error message, map why it's triggered, and propose a rewrite that tells users what happened, why, and how to fix it.

This is not a content-only pass. Most generic errors are symptoms of missing product/dev work — your audit must surface that too.

Step 1 — Inventory

Find every error message in the codebase. Cast a wide net:

# String literals near error keywords
rg -n --no-heading -i "(throw new Error|toast\.error|console\.error|notify\.error|setError|errorMessage|message:)" --type-add 'web:*.{ts,tsx,js,jsx,vue,svelte}' -t web -t py

# i18n / locale keys
rg -n --no-heading -i "error" --glob "**/*.{json,yaml,yml}" --glob "**/locales/**" --glob "**/i18n/**" --glob "**/translations/**"

# Status/toast/alert components
rg -n --no-heading "(<Alert|<Toast|<ErrorBoundary|<Banner)" --type-add 'web:*.{tsx,jsx,vue}' -t web

Adapt the patterns to whatever stack this repo actually uses. Check package.json / pyproject.toml / go.mod first to see what you're dealing with, then choose patterns accordingly.

Report the total count up front. Wix had 7,643 — give the user the equivalent number for this repo so they know the scope.

Step 2 — Classify

For each error message, place it in one of four buckets:

Bucket	Definition	Example
Generic	Says nothing useful	"Something went wrong", "An error occurred", "Failed"
Unclear	Tries to explain but uses jargon or confusing language	"Failed to fetch", "Credentials denied", "ECONNREFUSED"
Blame-passing	Shames the user or third parties	"You entered invalid data", "Stripe is down"
Acceptable	Says what happened, why, and how to fix	"We couldn't save your draft because you're offline. Your changes are kept locally and will sync when reconnected."

Skip the Acceptable bucket in your output — only surface what needs work.

Step 3 — Map the trigger

For each problem message, do the work a Wix dev would do during error mapping. Read the surrounding code and answer:

1. What code path triggers this? (function name, condition, file:line)
2. What's the actual underlying failure? (network? validation? auth? race condition? third-party API?)
3. How frequent is this likely to be? Infer from context — is it a hot path (auth, payment, save) or edge case?
4. Is it user-actionable? Can the user actually do anything about it, or do they need support?
5. What information do we have at the trigger site that we're throwing away? (error codes, field names, retry counts — anything the message could include but doesn't)

This step is the whole point. A rewrite without this mapping is just word-polish.

Step 4 — Propose rewrites

For each entry, output this structure:

### `path/to/file.ts:42`

**Current:** "Something went wrong"
**Bucket:** Generic
**Triggered by:** `saveInvoice()` catch block when Supabase RPC throws
**Underlying failure:** Network timeout OR RLS policy rejection — currently indistinguishable
**Frequency guess:** High (every save attempt)
**User-actionable:** Sometimes (network: yes, RLS: no)
**Info we're discarding:** `error.code`, `error.hint`, retry count

**Proposed rewrite (network case):**
> We couldn't save your invoice because the connection dropped. Your changes are kept on this device — we'll retry automatically when you're back online.

**Proposed rewrite (permission case):**
> We couldn't save this invoice because your account doesn't have permission for this workspace. Contact your admin or [reach support](#).

**Required code changes:**
- Distinguish error types in catch block (check `error.code`)
- Surface retry state to UI
- Add Sentry breadcrumb with `error.hint` for support diagnosis

Note that some rewrites require code changes, not just string changes. Flag those clearly — the user needs to know which fixes are 5-minute jobs versus tickets.

Step 5 — Summary table

End with a prioritized table sorted by impact (frequency × user-blocking):

Priority	File	Current	Bucket	Effort
P0	auth/login.ts:88	"Login failed"	Generic	Code change needed
P0	payment/checkout.ts:201	"Payment error"	Generic	Content + code
P1	forms/validate.ts:34	"Invalid input"	Unclear	Content only

P0 = hot path AND blocks user. P1 = hot path OR blocks user. P2 = everything else.

Voice rules for proposed rewrites

• Say what happened and why. If you don't know why, say "an issue on our end" — never blame the user, never name third parties.
• Tell them what's preserved ("your draft is saved", "no charge was made").
• Tell them what to do. If nothing, give an exit (contact support, retry link).
• "Please" only when the situation is genuinely dire. Otherwise it's filler.
• No "Oops!", no exclamation marks, no cutesy tone on financial/data-loss errors.
• Match the existing product voice — read a few non-error strings to calibrate before rewriting.

What not to do

• Don't rewrite without mapping the trigger first. That's how you end up with prettier lies.
• Don't propose a single "better generic" message to replace all generics. The whole point is they shouldn't be generic.
• Don't touch error messages whose text comes from a third-party SDK unless you can intercept and rewrite them at the boundary.
• Don't quietly fix anything. This is an audit — output proposals, let the user decide what ships.

Final output

Begin with: Audited N error messages across M files. Found X generic, Y unclear, Z blame-passing.

Then the per-file breakdowns, then the priority table.

If the codebase has more than ~50 problem messages, batch by directory or feature area and ask the user which area to drill into first. Don't drown them.