@kensaurus/skills 0.0.0-stage → 2.1.0

package/skills/backend-error-handling/SKILL.md

@@ -0,0 +1,489 @@
+---
+name: backend-error-handling
+description: >
+  Implement error-handling patterns: boundaries, toasts, one API error shape.
+  Use when "error boundary", "error toast", or "standardize API errors".
+  Plan-only audit → plan-error-handling. Sentry triage → debug-sentry-monitor.
+license: MIT
+---
+
+# Error Handling Skill
+
+**Degree of freedom: MIXED.** Which layer and message `[HIGH freedom]`;
+existing-type/boundary probes `[LOW freedom — run exactly]`.
+
+## How to reason
+
+1. **Observe** — existing error types, boundaries, `ActionResult` / `ApiError`
+2. **Interpret** — missing layer vs inconsistent shape vs swallowed catch
+3. **Classify** — reuse-existing / extend-codes / add-boundary / toast-only
+4. **Severity** — unhandled 500 on a mutation outranks a missing toast
+
+## Worked example
+
+> **Observe:** `createUser` throws Prisma `P2002`; UI shows a blank catch; `ActionResult` already lives in `types/errors.ts`.
+> **Interpret:** known conflict is unmapped; no field/toast path.
+> **Classify:** reuse `ActionResult` + `CONFLICT`; toast the message; do not add a second error type.
+> **Verify:** duplicate email returns `{ success: false, error: { code: 'CONFLICT' } }`; form alert shown.
+
+## Self-critique before reporting
+
+- **Reuse shape** — searched `ActionResult` / `ApiError` / `error.tsx` before adding a type
+- **User-safe** — `INTERNAL_ERROR` is generic; PII is not in the client message
+- **Layered** — boundary + action result + toast, not toast-only
+- **Right owner** — plan-only observability audit → `plan-error-handling`; live Sentry triage → `debug-sentry-monitor`
+
+Layered error handling for full-stack apps: one action-result shape, boundaries, and toasts.
+
+## When to Use
+
+- Adding error handling to new features
+- Improving error user experience
+- Standardizing error responses
+- Debugging error propagation
+- Adding error monitoring
+
+## Check existing first  [LOW freedom — run exactly]
+
+**Before adding ANY error handling, verify:**
+
+1. **Check for existing error types:**
+```bash
+rg "type.*Error|interface.*Error" --type ts
+rg "ActionResult|ApiError" --type ts
+```
+
+2. **Check for existing error boundaries:**
+```bash
+ls -la app/error.tsx app/global-error.tsx
+rg "ErrorBoundary" --type tsx
+```
+
+3. **Check for existing error utilities:**
+```bash
+rg "formatError|handleError|reportError" --type ts
+ls -la src/lib/errors* src/lib/error* 2>/dev/null # @/lib/errors
+```
+
+4. **Check established error response patterns:**
+```bash
+rg "success: false|error:" src/features/*/server/ --type ts | head -10
+```
+
+**Why:** Inconsistent error handling confuses users and complicates debugging. Always follow established patterns.
+
+## Error Handling Layers  [HIGH freedom]
+
+```
+┌─────────────────────────────────────────┐
+│ UI Layer │
+│ - Error boundaries │
+│ - Form validation errors │
+│ - Toast notifications │
+├─────────────────────────────────────────┤
+│ Application Layer │
+│ - Server Action errors │
+│ - API route errors │
+│ - Business logic errors │
+├─────────────────────────────────────────┤
+│ Data Layer │
+│ - Database errors │
+│ - Validation errors (Zod) │
+│ - External API errors │
+└─────────────────────────────────────────┘
+```
+
+## Standard Error Types  [HIGH freedom]
+
+```typescript
+// types/errors.ts
+
+// Base error shape
+interface AppError {
+ code: string // Machine-readable: VALIDATION_ERROR
+ message: string // User-friendly message
+ details?: unknown // Additional context
+}
+
+// Action result pattern
+type ActionResult<T> =
+ | { success: true; data: T }
+ | { success: false; error: AppError }
+
+// Common error codes
+const ErrorCode = {
+ VALIDATION_ERROR: 'VALIDATION_ERROR',
+ NOT_FOUND: 'NOT_FOUND',
+ UNAUTHORIZED: 'UNAUTHORIZED',
+ FORBIDDEN: 'FORBIDDEN',
+ CONFLICT: 'CONFLICT',
+ RATE_LIMITED: 'RATE_LIMITED',
+ INTERNAL_ERROR: 'INTERNAL_ERROR',
+} as const
+```
+
+## Server Action Error Handling  [HIGH freedom]
+
+```typescript
+// features/users/server/actions.ts
+'use server'
+
+import { z } from 'zod'
+import { revalidatePath } from 'next/cache'
+
+const CreateUserSchema = z.object({
+ email: z.string().email('Invalid email address'),
+ name: z.string().min(1, 'Name is required'),
+})
+
+export async function createUser(
+ prevState: ActionResult<User>,
+ formData: FormData
+): Promise<ActionResult<User>> {
+ try {
+ // 1. Validate input
+ const validated = CreateUserSchema.safeParse({
+ email: formData.get('email'),
+ name: formData.get('name'),
+ })
+
+ if (!validated.success) {
+ return {
+ success: false,
+ error: {
+ code: 'VALIDATION_ERROR',
+ message: 'Invalid input',
+ details: validated.error.flatten().fieldErrors,
+ },
+ }
+ }
+
+ // 2. Check authorization
+ const session = await auth()
+ if (!session) {
+ return {
+ success: false,
+ error: {
+ code: 'UNAUTHORIZED',
+ message: 'Please sign in to continue',
+ },
+ }
+ }
+
+ // 3. Execute business logic
+ const user = await db.user.create({
+ data: validated.data,
+ })
+
+ revalidatePath('/users')
+
+ return { success: true, data: user }
+
+ } catch (error) {
+ // 4. Handle known errors
+ if (error instanceof Prisma.PrismaClientKnownRequestError) {
+ if (error.code === 'P2002') {
+ return {
+ success: false,
+ error: {
+ code: 'CONFLICT',
+ message: 'A user with this email already exists',
+ },
+ }
+ }
+ }
+
+ // 5. Log unknown errors, return generic message
+ console.error('createUser error:', error)
+
+ return {
+ success: false,
+ error: {
+ code: 'INTERNAL_ERROR',
+ message: 'Something went wrong. Please try again.',
+ },
+ }
+ }
+}
+```
+
+## Form Error Display (React 19+)  [HIGH freedom]
+
+```tsx
+// components/UserForm.tsx
+'use client'
+
+import { useActionState } from 'react'
+import { useFormStatus } from 'react-dom'
+import { createUser } from '@/features/users/server/actions'
+
+// Separate submit button to use useFormStatus
+function SubmitButton() {
+ const { pending } = useFormStatus()
+ return (
+ <button type="submit" disabled={pending}>
+ {pending ? 'Creating...' : 'Create User'}
+ </button>
+ )
+}
+
+export function UserForm() {
+ const [state, action, isPending] = useActionState(createUser, null)
+
+ // Get field errors from validation
+ const fieldErrors = state?.success === false
+ ? state.error.details as Record<string, string[]>
+ : {}
+
+ return (
+ <form action={action}>
+ {/* Global error */}
+ {state?.success === false && state.error.code !== 'VALIDATION_ERROR' && (
+ <div role="alert" className="bg-red-50 text-red-700 p-3 rounded-lg mb-4">
+ {state.error.message}
+ </div>
+ )}
+
+ {/* Field with error */}
+ <div>
+ <label htmlFor="email">Email</label>
+ <input
+ id="email"
+ name="email"
+ type="email"
+ aria-invalid={!!fieldErrors.email}
+ aria-describedby={fieldErrors.email ? 'email-error' : undefined}
+ className={fieldErrors.email ? 'border-red-500' : ''}
+ />
+ {fieldErrors.email && (
+ <p id="email-error" className="text-red-600 text-sm mt-1">
+ {fieldErrors.email[0]}
+ </p>
+ )}
+ </div>
+
+ <SubmitButton />
+ </form>
+ )
+}
+```
+
+**React 19 Form Patterns:**
+- `useActionState` - Form state with Server Actions
+- `useFormStatus` - Pending state in child components
+- `useOptimistic` - Optimistic UI updates
+
+## React Error Boundaries  [HIGH freedom]
+
+```tsx
+// app/error.tsx (Next.js page error boundary)
+'use client'
+
+import { useEffect } from 'react'
+
+export default function Error({
+ error,
+ reset,
+}: {
+ error: Error & { digest?: string }
+ reset: () => void
+}) {
+ useEffect(() => {
+ // Log to error reporting service
+ console.error('Page error:', error)
+ }, [error])
+
+ return (
+ <div className="flex flex-col items-center justify-center min-h-[400px]">
+ <h2 className="text-xl font-semibold mb-4">Something went wrong</h2>
+ <p className="text-muted-foreground mb-6">
+ We're sorry, but something unexpected happened.
+ </p>
+ <button
+ onClick={reset}
+ className="px-4 py-2 bg-primary text-primary-foreground rounded-lg"
+ >
+ Try again
+ </button>
+ </div>
+ )
+}
+
+// app/global-error.tsx (root error boundary)
+'use client'
+
+export default function GlobalError({
+ error,
+ reset,
+}: {
+ error: Error & { digest?: string }
+ reset: () => void
+}) {
+ return (
+ <html>
+ <body>
+ <h2>Something went wrong!</h2>
+ <button onClick={reset}>Try again</button>
+ </body>
+ </html>
+ )
+}
+```
+
+## API Route Error Handling  [HIGH freedom]
+
+```typescript
+// app/api/products/route.ts
+import { NextRequest, NextResponse } from 'next/server'
+import { z } from 'zod'
+
+export async function POST(request: NextRequest) {
+ try {
+ const body = await request.json()
+
+ const validated = ProductSchema.safeParse(body)
+ if (!validated.success) {
+ return NextResponse.json(
+ {
+ error: {
+ code: 'VALIDATION_ERROR',
+ message: 'Invalid request body',
+ details: validated.error.flatten().fieldErrors,
+ },
+ },
+ { status: 400 }
+ )
+ }
+
+ const product = await db.product.create({ data: validated.data })
+
+ return NextResponse.json({ data: product }, { status: 201 })
+
+ } catch (error) {
+ if (error instanceof SyntaxError) {
+ return NextResponse.json(
+ { error: { code: 'INVALID_JSON', message: 'Invalid JSON body' } },
+ { status: 400 }
+ )
+ }
+
+ console.error('POST /api/products error:', error)
+
+ return NextResponse.json(
+ { error: { code: 'INTERNAL_ERROR', message: 'Internal server error' } },
+ { status: 500 }
+ )
+ }
+}
+```
+
+## TanStack Query Error Handling  [HIGH freedom]
+
+```tsx
+// hooks/useProducts.ts
+import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'
+import { toast } from 'sonner'
+
+export function useProducts() {
+ return useQuery({
+ queryKey: ['products'],
+ queryFn: async () => {
+ const res = await fetch('/api/products')
+ if (!res.ok) {
+ const error = await res.json()
+ throw new Error(error.error?.message || 'Failed to fetch products')
+ }
+ return res.json()
+ },
+ retry: (failureCount, error) => {
+ // Don't retry on 4xx errors
+ if (error.message.includes('401') || error.message.includes('403')) {
+ return false
+ }
+ return failureCount < 3
+ },
+ })
+}
+
+export function useCreateProduct() {
+ const queryClient = useQueryClient()
+
+ return useMutation({
+ mutationFn: async (data: ProductInput) => {
+ const res = await fetch('/api/products', {
+ method: 'POST',
+ body: JSON.stringify(data),
+ })
+ if (!res.ok) {
+ const error = await res.json()
+ throw new Error(error.error?.message || 'Failed to create product')
+ }
+ return res.json()
+ },
+ onSuccess: () => {
+ queryClient.invalidateQueries({ queryKey: ['products'] })
+ toast.success('Product created')
+ },
+ onError: (error) => {
+ toast.error(error.message)
+ },
+ })
+}
+```
+
+## Error State UI Components  [HIGH freedom]
+
+```tsx
+// components/ErrorState.tsx
+import { AlertCircle, RefreshCw } from 'lucide-react'
+
+interface ErrorStateProps {
+ title?: string
+ message: string
+ onRetry?: () => void
+}
+
+export function ErrorState({
+ title = 'Error',
+ message,
+ onRetry
+}: ErrorStateProps) {
+ return (
+ <div className="flex flex-col items-center justify-center py-12 text-center">
+ <AlertCircle className="h-12 w-12 text-red-500 mb-4" />
+ <h3 className="font-semibold text-lg mb-2">{title}</h3>
+ <p className="text-muted-foreground mb-6 max-w-sm">{message}</p>
+ {onRetry && (
+ <button
+ onClick={onRetry}
+ className="inline-flex items-center gap-2 px-4 py-2 border rounded-lg hover:bg-muted"
+ >
+ <RefreshCw className="h-4 w-4" />
+ Try again
+ </button>
+ )}
+ </div>
+ )
+}
+
+// Usage with TanStack Query
+function ProductList() {
+ const { data, error, isLoading, refetch } = useProducts()
+
+ if (error) {
+ return (
+ <ErrorState
+ title="Failed to load products"
+ message={error.message}
+ onRetry={() => refetch()}
+ />
+ )
+ }
+
+ // ...
+}
+```
+
+## Further reading
+
+- [Error Logging & Monitoring and more](references/details.md)

package/skills/backend-error-handling/references/details.md

@@ -0,0 +1,58 @@
+## Error Logging & Monitoring
+
+```typescript
+// lib/error-reporting.ts
+
+export function reportError(error: Error, context?: Record<string, unknown>) {
+  // Development: log to console
+  if (process.env.NODE_ENV === 'development') {
+    console.error('Error:', error, context)
+    return
+  }
+  
+  // Production: send to monitoring service
+  // Sentry example:
+  // Sentry.captureException(error, { extra: context })
+  
+  // Or custom logging:
+  fetch('/api/log-error', {
+    method: 'POST',
+    body: JSON.stringify({
+      message: error.message,
+      stack: error.stack,
+      context,
+      timestamp: new Date().toISOString(),
+    }),
+  }).catch(() => {}) // Don't throw on logging failure
+}
+```
+
+## Error Handling Checklist
+
+### Server Side
+- [ ] All Server Actions return `ActionResult<T>`
+- [ ] Zod validation with user-friendly messages
+- [ ] Known errors caught and mapped
+- [ ] Unknown errors logged, generic message returned
+- [ ] No sensitive info in error messages
+
+### Client Side
+- [ ] Error boundaries at page level
+- [ ] Global error boundary for catastrophic failures
+- [ ] Form field errors displayed inline
+- [ ] Global errors shown in alert/toast
+- [ ] Loading states during async operations
+- [ ] Retry buttons where appropriate
+
+### API
+- [ ] Consistent error response shape
+- [ ] Appropriate HTTP status codes
+- [ ] Validation errors include field details
+- [ ] Rate limiting with 429 response
+- [ ] No stack traces in production
+
+### Monitoring
+- [ ] Error logging configured
+- [ ] Alerts for critical errors
+- [ ] Error rates tracked
+- [ ] User-facing errors monitored

package/skills/backend-observability/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: backend-observability
+description: >
+  Implement correlated errors, traces, and structured logs with PII redaction.
+  Use when "add logging", "instrument this", or wiring Sentry/Langfuse.
+  Plan-only audit → plan-error-handling. Sentry triage → debug-sentry-monitor.
+license: MIT
+---
+
+# Observability Instrumentation
+
+**Degree of freedom: MIXED.** What to wrap and alert on `[HIGH freedom]`;
+correlation ids, PII redaction, and the DoD `[LOW freedom — run exactly]`.
+
+## How to reason
+
+1. **Observe** — which ids, logs, spans, and PII already exist
+2. **Interpret** — can you pivot error ↔ trace ↔ log ↔ user from any one?
+3. **Classify** — add-correlation / convert-console / redact / wrap-span / alert
+4. **Severity** — uncorrelated prod 500 outranks a missing debug field
+
+## Worked example
+
+> **Observe:** checkout 500 in Sentry has no request_id; pino logs the cart id; no LLM (Langfuse unused).
+> **Interpret:** cannot pivot error → logs; webhook still `console.log`s.
+> **Classify:** ALS request_id on logs + `Sentry.setTag`; convert console to pino; redact `Authorization`.
+> **Verify:** one id on the Sentry event and the log line; `beforeSend` strips the header.
+
+## Self-critique before reporting
+
+- **Correlated** — same request/trace id on the log, Sentry, and Langfuse
+- **Redacted** — deny-list at the logger + `beforeSend`, not per-call hope
+- **Leveled** — no `console.log` in prod; handled paths are not `error`
+- **Right owner** — plan-only audit → `plan-error-handling`; investigate a Sentry issue → `debug-sentry-monitor`
+
+> The build-time counterpart to your monitoring stack. The Sentry plugin installs the SDK; `debug-sentry-monitor` triages after the fact; `audit-langfuse-llm` audits LLM traces. This skill is about instrumenting **correctly while you build** so those tools have signal to work with — and so a 3am incident is debuggable.
+
+## When this fires
+Adding logging / tracing / metrics to new code, reviewing instrumentation, or fixing "we can't tell what happened in prod." Not for installing an SDK (use the Sentry/Langfuse plugins) or post-hoc triage (use the monitor/audit skills).
+
+## The one rule that matters most: correlation  [LOW freedom — run exactly]
+A prod incident is only debuggable if you can pivot **error ↔ trace ↔ log ↔ user** from any one of them. Make every layer share an id.
+
+- Generate/propagate a **request id** (or OTel `trace_id`) at the entry point (HTTP middleware, edge function, job start). Put it in async context (`AsyncLocalStorage` / context var), not a parameter threaded everywhere.
+- **Stamp it on everything:** every log line, Sentry `setTag("request_id", id)` / `setContext`, and the Langfuse trace (`trace.id` or metadata). On an LLM error, attach the Langfuse trace URL to the Sentry event so you jump straight from the error to the prompt/response.
+- Set user/session/tenant scope (`Sentry.setUser`, Langfuse `userId`/`sessionId`) — scrubbed (see redaction).
+
+## Structured logging discipline  [HIGH freedom]
+- **Structured, not string-soup.** Emit JSON with stable fields (`level`, `msg`, `request_id`, `event`, domain ids). One event per line. Use the platform logger (pino / structlog / slog), not bare `console.log`.
+- **Levels mean things:** `error` = needs a human; `warn` = degraded but handled; `info` = state transitions / business events; `debug` = dev-only, off in prod. Don't log `error` for handled flow.
+- **No `console.log` shipped to prod** — it's unsearchable, unleveled, and a PII leak risk. Remove or convert to a leveled structured log.
+- **Log decisions, not noise:** log the branch taken + key inputs/outputs at boundaries, not every line. A log you'd never grep is cost, not signal.
+
+## PII / secret redaction (non-negotiable)  [LOW freedom — run exactly]
+- Never log tokens, passwords, API keys, full PANs, auth headers, or raw request bodies. Redact at the logger/transport layer (deny-list keys + pattern scrub) so it can't be bypassed per-call.
+- Configure Sentry `beforeSend` / data-scrubbing and Langfuse masking to strip PII from events/traces. Assume anything you put in a span/breadcrumb may be retained.
+- For LLM traces: decide explicitly whether prompts/completions may contain PII; mask or hash before sending if the jurisdiction requires it.
+
+## Tracing / spans (what to wrap)  [HIGH freedom]
+- Wrap **boundaries and slow/fallible work**: inbound request, outbound HTTP/DB/queue calls, LLM calls, background jobs. Not every function.
+- Name spans by operation (`http.server`, `db.query`, `llm.generate`), add attributes (route, status, row count, model) — follow **OTel semantic conventions**, including the **GenAI conventions** for LLM spans (model, tokens in/out, cost, latency, temperature).
+- **Sampling:** you don't need 100%. Head-sample normal traffic (e.g. 10–20%), but **always keep errors and slow outliers**. Document the rate; it's a cost/visibility dial.
+
+## LLM-specific (Langfuse)  [HIGH freedom]
+- Capture per generation: prompt, response, model, input/output tokens, cost, latency, and the eval/score if you run one. Group multi-step agents under one trace with nested spans.
+- Link the Langfuse `trace_id` into the surrounding request id and into Sentry on failure — so an LLM error in Sentry is one click from the full trace.
+- Tag traces with `userId` / `sessionId` / release so `audit-langfuse-llm` can slice quality by cohort.
+
+## Alerts & SLOs (signal, not noise)  [HIGH freedom]
+- Alert on **symptoms users feel** (error-rate spike, p95 latency, checkout/login failure, LLM eval-score drop), not every error. A pager that cries wolf gets muted.
+- Define a few SLOs (availability, latency, key-flow success) and alert on burn rate, not raw counts.
+- Every alert names an owner and a first action. Route via `sentry-create-alert` / your channel.
+
+## Definition of done  [LOW freedom — do not skip]
+- [ ] A shared request/trace id is on every log line, the Sentry scope, and the Langfuse trace.
+- [ ] From a prod error you can reach the trace, the logs, and the user in ≤2 clicks.
+- [ ] Logs are structured + correctly leveled; no `console.log` shipped to prod.
+- [ ] PII/secret redaction is enforced at the logger + Sentry `beforeSend` + Langfuse masking.
+- [ ] Spans cover boundaries with OTel-conventional names/attributes; errors are never sampled out.
+- [ ] LLM generations record model/tokens/cost/latency and link back to the request id.
+- [ ] Alerts fire on user-felt symptoms with an owner, not on every error.
+
+## Composes with
+- Sentry plugin (`sentry-sdk-setup`, `sentry-setup-ai-monitoring`, `sentry-create-alert`, `sentry-otel-exporter-setup`) — SDK + alert wiring.
+- Langfuse plugin (`langfuse`) + `audit-langfuse-llm` — LLM trace capture + quality audit.
+- `debug-sentry-monitor` / `debug-error` — post-hoc triage of what this instrumentation surfaces.
+- `data-pipeline` — per-run pipeline metrics use these same correlation + logging rules.
+- `workflow-spec-tdd` — make "observable" part of the spec's "done when", not an afterthought.