ops-error-classifier
/ops-error-classifier
Use when an error occurs anywhere in the legal AI request pipeline and a structured response decision is needed. Classifies errors into six categories (transient, provider, client-input, auth/quota, backend-bug, schema/data-integrity) and outputs the correct action (retry, failover, user guidance, upgrade flow, ticket, escalation) along with a user-facing message and an optional internal ticket reference.
- Author
- sboghossian ↗
- Repository
- mini-claude-for-legal ↗
- Licence
- MIT
- Last repository change
- 14.05.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 14.05.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Use when an error occurs anywhere in the legal AI request pipeline and a structured response decision is needed. Classifies errors into six categories (transient, provider, client-input, auth/quota, backend-bug, schema/data-integrity) and outputs the correct action (retry, failover, user guidance, upgrade flow, ticket, escalation) along with a user-facing message and an optional internal ticket reference.
Original author description
Use when an error occurs anywhere in the legal AI request pipeline and a structured response decision is needed. Classifies errors into six categories (transient, provider, client-input, auth/quota, backend-bug, schema/data-integrity) and outputs the correct action (retry, failover, user guidance, upgrade flow, ticket, escalation) along with a user-facing message and an optional internal ticket reference.
How it works
- Purpose
- Classification schema
- Output schema
- Where this skill is used
- Related skills
SKILL.md preview
---
name: ops-error-classifier
description: Use when an error occurs anywhere in the legal AI request pipeline and a structured response decision is needed. Classifies errors into six categories (transient, provider, client-input, auth/quota, backend-bug, schema/data-integrity) and outputs the correct action (retry, failover, user guidance, upgrade flow, ticket, escalation) along with a user-facing message and an optional internal ticket reference.
license: MIT
metadata:
id: ops.error-classifier
category: ops
jurisdictions: [__multi__]
priority: P2
intent: [error, ops, error-handling, retry, failover]
related: [ops-crash-report-formatter, ops-bug-report-collector, ops-linear-triage-from-chat-bug-report, ops-subscription-erd-validator]
source: Louis — HAQQ Legal AI (github.com/sboghossian/mini-claude-for-legal)
version: "1.0"
---
# Ops — Error Classifier
## Purpose
Not all errors should be handled the same way. A timeout from an LLM provider is different from a malformed user upload, which is different from an expired API key, which is different from a schema bug. This skill classifies every error by type and outputs the correct action, user message, and internal routing — so that error boundaries in the frontend and middleware in the backend always respond appropriately.
## Classification schema
Errors are classified into six categories:
### 1. Transient
**Definition**: Network-level or infrastructure-level failures that are likely self-resolving.
**Examples**: request timeout, rate-limit (429), network disconnect, brief database unavailability.
**Action**: Automatic retry with exponential backoff (max 3 attempts). If all retries fail, escalate to Provider category.
**User message**: "Something went wrong — retrying automatically."
**Internal ticket**: None for first occurrence; flag if the same transient error recurs >3× in 5 minutes.
### 2. Provider
**Definition**: LLM provider (Anthropic, OpenAI, Google, etc.) returns a 5xx or sustained unavailability.
**Examples**: Anthropic 503, OpenAI 500, Gemini rate limit for the tenant's project.
**Action**: Fail over to the next configured provider in the failover chain (e.g., Claude Sonnet → GPT-4o → Gemini Pro). Log the failover.
**User message**: "We're experiencing a brief technical issue. Switching to an alternative AI provider."
**Internal ticket**: Create a linear note if the failover persists >10 minutes; page on-call if it persists >30 minutes.
### 3. Client input
**Definition**: The error is caused by the user's input or uploaded content.
**Examples**: Oversized file upload (>50MB), unsupported file format, corrupted PDF, prompt exceeds context limit.
**Action**: Do not retry. Return user-friendly guidance.
**User message**: Specific to the error — e.g., "This file is too large (max 50MB). Try compressing it or splitting into sections." Never say "bad input" — always describe what the user can do.
**Internal ticket**: None. Log for aggregate analysis only.
### 4. Auth / quota
**Definition**: The user or tenant does not have permission or credits for the requested operation.
**Examples**: Out of monthly credits, expired session token, API key revoked, BYO-key quota exhausted.
**Action**: Redirect to the appropriate resolution flow.
- Expired token → silent re-auth or login prompt.
- Out of credits → [[onboarding-upgrade-prompt-when-credits-low]].
- BYO-key quota → prompt user to check their API key settings.
**User message**: Context-appropriate (not a generic error).
**Internal ticket**: Log credit exhaustion events for burn-rate watcher. No ticket for auth flows.
### 5. Backend bug
**Definition**: An unhandled exception or logic error in the application code.
**Examples**: NullPointerException, unhandled promise rejection, wrong database query returning empty set unexpectedly.
**Action**: Show a generic error to the user. Create a P-level Linear ticket automatically.
**User message**: "Something went wrong on our end. The team has been notified."
**Internal ticket**: Auto-create in Linear with stack trace, session context, user ID (anonymized), and severity (auto-classified from impact). See [[ops-crash-report-formatter]] for formatting.
### 6. Schema / data integrity
**Definition**: Data in the database or a data model violates an expected constraint or schema.
**Examples**: User has two active subscriptions (violates 1-1 constraint), null field in a required column, foreign key pointing to a deleted record.
**Action**: Halt the operation. Create a DBA escalation ticket. Do not attempt to proceed with corrupt data.
**User message**: "We encountered a data issue with your account. Our team has been notified and will reach out within 24 hours."
**Internal ticket**: High-priority Linear issue assigned to the DBA or backend lead. Include the failing entity IDs (anonymized) and the violated constraint.
## Output schema
Every classified error produces the following output:
```json
{
"errorClass": "transient | provider | client-input | auth-quota | backend-bug | schema-integrity",
"action": "retry | failover | user-guidance | upgrade-flow | re-auth | p-level-ticket | dba-escalation",
"userMessage": "<string — plain language, no jargon>",
"internalTicket": {
"create": true | false,
"severity": "P0 | P1 | P2 | P3 | null",
"assignee": "<team or role>",
"summary": "<string>"
},
"retryable": true | false,
"retryAfterMs": <number | null>
}
```
## Where this skill is used
- **Frontend error boundaries**: React error boundaries and API call wrappers call the classifier to determine whether to show a retry button, a guidance message, or a generic error screen.
- **Backend middleware**: API request handlers pass unhandled exceptions through the classifier before responding to the client.
- **Skill router**: when a skill invocation fails, the router uses the classifier to decide whether to retry with the same skill, switch to a fallback skill, or surface an error.
## Related skills
- [[ops-crash-report-formatter]] — formats backend-bug class errors into structured incident tickets
- [[ops-bug-report-collector]] — collects user-reported issues that may accompany classified errors
- [[ops-linear-triage-from-chat-bug-report]] — triage workflow for P-level tickets created by this classifier
- [[ops-subscription-erd-validator]] — used when the classifier detects schema-integrity errors related to billing
Versions
The database has no other skills named ops-error-classifier.
Database snapshot: 13.11.2026 · package version d91a90818a13 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100rs-domain-error
Use when designing domain error handling. Keywords: domain error, error categorization, recovery strategy, retry, fallback, domain error hierarchy, user-facing vs internal errors, error code design, circuit breaker, graceful degradation, resilience, error context, backoff, retry… - 100error-handling
Patterns for robust error handling across TypeScript, Python, and Go. Covers typed errors, error boundaries, retries, circuit breakers, and user-facing error messages. Use when designing error types, retries, circuit breakers, or user-facing failure messages in TypeScript, Python, or Go.