@skill-graph/cli 0.5.6

package/marketplace/skills/error-boundary/SKILL.md

@@ -0,0 +1,235 @@
+---
+name: error-boundary
+description: "Use when designing or reviewing React error boundaries: what an error boundary catches (rendering errors, lifecycle errors, constructor errors) and what it does not (event handler errors, async errors, SSR errors, errors in the boundary itself), why React still requires class components for error boundaries, how to place boundaries by granularity (page / feature / leaf), how error boundaries pair with Suspense, the reset-and-recover pattern (resetKeys, error.reset), the Next.js error.tsx route-segment convention, and how to integrate boundaries with error reporting (Sentry, observability). Covers React 18+ and Next.js App Router. Do NOT use for Suspense boundary placement (use suspense-patterns), for general error-handling discipline (try/catch in async code, validation errors), for backend error contracts (use api-design), or for observability infrastructure (use error-tracking)."
+license: MIT
+allowed-tools: Read Grep
+metadata:
+  metadata: "{\"schema_version\":6,\"version\":\"1.0.0\",\"type\":\"capability\",\"category\":\"engineering\",\"domain\":\"engineering/frontend\",\"scope\":\"reference\",\"owner\":\"skill-graph-maintainer\",\"freshness\":\"2026-05-16\",\"drift_check\":\"{\\\\\\\"last_verified\\\\\\\":\\\\\\\"2026-05-16\\\\\\\"}\",\"eval_artifacts\":\"planned\",\"eval_state\":\"unverified\",\"routing_eval\":\"absent\",\"comprehension_state\":\"present\",\"stability\":\"experimental\",\"keywords\":\"[\\\\\\\"React Error Boundary\\\\\\\",\\\\\\\"componentDidCatch\\\\\\\",\\\\\\\"getDerivedStateFromError\\\\\\\",\\\\\\\"react-error-boundary library\\\\\\\",\\\\\\\"Next.js error.tsx\\\\\\\",\\\\\\\"global-error.tsx\\\\\\\",\\\\\\\"error boundary granularity\\\\\\\",\\\\\\\"resetKeys\\\\\\\",\\\\\\\"error boundary with Suspense\\\\\\\",\\\\\\\"caught render error\\\\\\\",\\\\\\\"uncaught event handler error\\\\\\\",\\\\\\\"catch errors in React component tree\\\\\\\",\\\\\\\"show fallback UI when component crashes\\\\\\\",\\\\\\\"where to place error boundaries\\\\\\\",\\\\\\\"React component crash recovery\\\\\\\",\\\\\\\"error.tsx route segment fallback\\\\\\\"]\",\"triggers\":\"[\\\\\\\"my error boundary isn't catching errors\\\\\\\",\\\\\\\"do I need an error boundary here\\\\\\\",\\\\\\\"why does the whole page crash on one component error\\\\\\\",\\\\\\\"how do I recover from a caught error\\\\\\\",\\\\\\\"error.tsx vs global-error.tsx\\\\\\\",\\\\\\\"why doesn't this catch async errors\\\\\\\"]\",\"examples\":\"[\\\\\\\"design a route-segment error.tsx for a dashboard so one failing widget doesn't blank the whole page\\\\\\\",\\\\\\\"diagnose why a click-handler crash bypasses the error boundary and propagates to window.onerror\\\\\\\",\\\\\\\"pair an error boundary with a Suspense boundary so failed fetches show error UI while successful ones stream in\\\\\\\",\\\\\\\"integrate an error boundary with Sentry so caught errors are reported with the component tree context\\\\\\\"]\",\"anti_examples\":\"[\\\\\\\"design where to place Suspense fallback boundaries (use suspense-patterns)\\\\\\\",\\\\\\\"design the API response contract for a 500 error (use api-design)\\\\\\\",\\\\\\\"set up Sentry SDK initialization (use error-tracking)\\\\\\\",\\\\\\\"handle a Promise rejection in an event handler (use code-review for the local try/catch pattern)\\\\\\\",\\\\\\\"configure the Sentry, Datadog, or other error-tracking SDK and dashboards (use error-tracking)\\\\\\\"]\",\"relations\":\"{\\\\\\\"related\\\\\\\":[\\\\\\\"suspense-patterns\\\\\\\",\\\\\\\"hooks-patterns\\\\\\\",\\\\\\\"error-tracking\\\\\\\",\\\\\\\"server-components-design\\\\\\\"],\\\\\\\"boundary\\\\\\\":[{\\\\\\\"skill\\\\\\\":\\\\\\\"suspense-patterns\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"suspense-patterns owns the loading-state boundary mechanism; error-boundary owns the failure-state boundary mechanism. They pair in the canonical ErrorBoundary→Suspense→Component nesting but are distinct primitives that catch different signals (thrown Error vs thrown Promise).\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"hooks-patterns\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"hooks-patterns covers component-internal logic discipline; error-boundary is a tree-level mechanism that handles failures from anywhere in its descendant subtree. Class-component requirement of error boundaries is the one place hooks discipline does not apply.\\\\\\\"}],\\\\\\\"verify_with\\\\\\\":[\\\\\\\"code-review\\\\\\\",\\\\\\\"error-tracking\\\\\\\"]}\",\"mental_model\":\"|\",\"purpose\":\"|\",\"boundary\":\"|\",\"analogy\":\"An error boundary is to React's component tree what a circuit breaker is to a building's electrical system — when a fault occurs in one circuit, the breaker for THAT circuit trips, isolating the fault so the rest of the building keeps running, while sub-panels still healthy on other circuits keep lights and outlets working. A single master breaker would protect against fault propagation but at the cost of darkening everything; the right granularity is one breaker per useful zone.\",\"misconception\":\"|\",\"concept\":\"{\\\\\\\"definition\\\\\\\":\\\\\\\"An error boundary is a React component that catches JavaScript errors thrown anywhere in its descendant tree during rendering, in lifecycle methods, and in constructors — and renders a fallback UI instead of unmounting the broken subtree to the root. As of React 19 it must still be implemented as a class component using getDerivedStateFromError and/or componentDidCatch; function components cannot themselves be error boundaries (they can render one and provide its fallback). React's design choice: failure in a subtree should not require crashing the whole tree, but the boundary itself must be a stable component above the failure point.\\\\\\\",\\\\\\\"mental_model\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"purpose\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"boundary\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"taxonomy\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"analogy\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"misconception\\\\\\\":\\\\\\\"|\\\\\\\"}\",\"skill_graph_source_repo\":\"https://github.com/jacob-balslev/skill-graph\",\"skill_graph_protocol\":\"Skill Metadata Protocol v5\",\"skill_graph_project\":\"Skill Graph\",\"skill_graph_canonical_skill\":\"skills/error-boundary/SKILL.md\"}"
+  skill_graph_source_repo: "https://github.com/jacob-balslev/skill-graph"
+  skill_graph_protocol: Skill Metadata Protocol v4
+  skill_graph_project: Skill Graph
+  skill_graph_canonical_skill: skills/error-boundary/SKILL.md
+---
+
+# Error Boundary
+
+## Coverage
+
+The discipline of placing and configuring React error boundaries: precisely what the boundary catches (rendering errors, lifecycle method errors, constructor errors) and what it provably cannot catch (event handler errors, async/setTimeout/Promise errors, server-side rendering errors before React 18.5, errors thrown by the boundary itself), why React 19 still requires class-component implementation, the boundary-placement granularity tradeoff (page / feature / leaf), the canonical Suspense+ErrorBoundary nesting and why their order matters, the reset-and-recover pattern via `resetKeys` / `FallbackComponent`, the Next.js App Router conventions (`error.tsx`, `global-error.tsx`), and how to wire boundaries to external error reporting so caught errors do not become silent UI degradation.
+
+## Philosophy
+
+Before React 16, an error thrown during render had nowhere to go. React's reconciler would catch it, log it, and continue trying to render — usually producing a corrupted or blank tree. The component model assumed that render functions don't throw, and the runtime had no recovery primitive when they did. The result was either total app crash or partial blank screens with no signal that anything had broken.
+
+Error boundaries gave React the recovery primitive it had been missing. A class component that implements `getDerivedStateFromError` and/or `componentDidCatch` catches throws from anywhere in its descendant subtree during rendering, lifecycle methods, and constructors. When a throw occurs, React unmounts the broken subtree and renders the boundary's fallback in its place. The rest of the tree, outside the boundary, keeps running. A bug in one widget no longer means a blank page; it means that widget shows its fallback and everything else is fine.
+
+The discipline is to **place boundaries by failure-blast-radius**. A boundary near the page root catches everything but replaces the entire page on any error. A boundary around a single widget catches only that widget's errors but lets the rest of the page keep working. The right granularity is the smallest scope where the fallback UI is still meaningful: a chart's error fallback ("Unable to load chart, retry?") is useful per-chart; a global "Something went wrong" replacing the whole app is useful only as a last resort.
+
+The boundary's most important second-order property is **honesty**. A caught error is still an error. A boundary that swallows the throw without reporting externally degrades the UI silently — users see "Something went wrong," developers see nothing. The discipline is to pair every boundary with a report-to-Sentry (or equivalent) call, so the fallback is the user-facing recovery *and* the developer-facing alarm.
+
+## What an Error Boundary Catches — and Doesn't
+
+| Source of error | Caught by boundary? |
+|---|---|
+| Throw during a component's render | Yes |
+| Throw in `componentDidMount` / `componentDidUpdate` | Yes |
+| Throw in a class constructor | Yes |
+| Throw during hook execution (useState initializer, useEffect's render-phase setup) | Yes |
+| Throw in a `useEffect` callback body | **No** — runs after commit, outside render phase |
+| Throw in an event handler (`onClick`, `onChange`) | **No** — runs imperatively, outside render |
+| Unhandled Promise rejection (async function thrown into a click handler) | **No** — async errors propagate to `window.onunhandledrejection` |
+| `setTimeout` / `setInterval` callback throw | **No** — escapes React's call stack |
+| Server-side rendering error (`renderToString` throw before React 18.5) | Partially — handled via `onError` in modern streaming APIs |
+| Error thrown by the boundary itself | **No** — propagates to the next ancestor boundary |
+
+The pattern: error boundaries catch errors thrown **inside React's call stack during render or lifecycle**. Errors that happen outside that stack — event handlers, async callbacks, promise rejections — must be handled with a local `try/catch` and then surfaced into React via `setState` (so the boundary catches the re-render with the error state).
+
+Canonical async-error pattern:
+
+```tsx
+function MyComponent() {
+  const [error, setError] = useState<Error | null>(null)
+  if (error) throw error   // ← rethrow into render, so the boundary catches it
+  
+  return (
+    <button onClick={async () => {
+      try {
+        await doRiskyThing()
+      } catch (e) {
+        setError(e as Error)   // ← surface async error into state
+      }
+    }}>
+      Click
+    </button>
+  )
+}
+```
+
+This pattern is verbose but explicit. The boundary catches all *rendering* errors automatically; async errors must be opted-in by re-throwing during render.
+
+## React Still Requires a Class Component
+
+Despite the rest of React moving to function components and hooks, error boundaries must be class components as of React 19. The reason: the boundary's defining methods are `static getDerivedStateFromError` and `componentDidCatch`, which have no hooks equivalent. The React team has discussed `useErrorBoundary` but it has not shipped.
+
+Minimal class boundary:
+
+```tsx
+import { Component, ReactNode } from 'react'
+
+class ErrorBoundary extends Component<
+  { fallback: ReactNode; children: ReactNode; onError?: (e: Error) => void },
+  { hasError: boolean }
+> {
+  state = { hasError: false }
+  
+  static getDerivedStateFromError() {
+    return { hasError: true }
+  }
+  
+  componentDidCatch(error: Error, info: React.ErrorInfo) {
+    this.props.onError?.(error)
+    // Report to Sentry/Datadog/etc here
+  }
+  
+  render() {
+    return this.state.hasError ? this.props.fallback : this.props.children
+  }
+}
+```
+
+In practice, use [`react-error-boundary`](https://github.com/bvaughn/react-error-boundary) by Brian Vaughn / Kent C. Dodds — it provides `<ErrorBoundary>` with reset support, `FallbackComponent`, `resetKeys`, and `onError` / `onReset` props out of the box. Implementing the class yourself is fine, but `react-error-boundary` covers the cases (recovery, key-based reset) you'll eventually want.
+
+## Granularity — Where to Place the Boundary
+
+Three placement strategies, each correct in different contexts:
+
+**1. App-root boundary.** One boundary at the top, catches everything else's failures. Renders a "Something went wrong" generic page.
+
+- **Use as**: backstop only. The last line of defense if every finer-grained boundary fails or doesn't exist.
+- **Don't rely on alone**: when this catches an error, the user has lost everything.
+
+**2. Route-segment boundary** (Next.js `error.tsx`). One boundary per page or layout segment.
+
+- **Use when**: each route is a meaningful unit; failure in one route shouldn't blank the whole app shell.
+- **Next.js sugar**: an `app/dashboard/error.tsx` file is automatically a route-scoped boundary around `app/dashboard/page.tsx`. A `global-error.tsx` is the app-root backstop.
+
+**3. Feature/widget boundary.** A boundary around each independent feature or data-loading component.
+
+- **Use when**: many features render in parallel and failure in one shouldn't take down siblings (dashboard widgets, list-of-items where one item's data is malformed).
+- **Cost**: more fallback UIs to design; potential "many error messages" surface.
+
+The right approach is layered: app-root + route-segment + feature, with each catching what its layer scopes. A leaf widget's error hits the feature boundary; an unhandled error in the feature boundary hits the route boundary; a catastrophic error in the route boundary hits the app-root boundary.
+
+## Pairing with Suspense
+
+Error boundaries catch *thrown Errors*. Suspense boundaries catch *thrown Promises*. They are distinct mechanisms and must be different components, but they almost always nest together:
+
+```tsx
+<ErrorBoundary fallback={<ErrorUI />}>
+  <Suspense fallback={<LoadingUI />}>
+    <DataLoadingComponent />
+  </Suspense>
+</ErrorBoundary>
+```
+
+Order matters:
+
+- **ErrorBoundary outside Suspense**: a failed fetch replaces the entire group (loading state too) with the error UI. Most applications want this — a single failure surface.
+- **Suspense outside ErrorBoundary**: the Suspense fallback shows during loading; if the fetch then fails, the inner error UI takes its place inside the Suspense slot. Useful when the loading state should remain visible for everything else and only a small portion swaps to error.
+
+`react-error-boundary` provides `onReset` that pairs with Suspense's transition APIs to retry a failed fetch:
+
+```tsx
+<ErrorBoundary
+  fallbackRender={({ resetErrorBoundary }) => (
+    <ErrorUI onRetry={resetErrorBoundary} />
+  )}
+  resetKeys={[queryId]}
+>
+  <Suspense fallback={<Spinner />}>
+    <QueryResult queryId={queryId} />
+  </Suspense>
+</ErrorBoundary>
+```
+
+When `queryId` changes (e.g., user clicks a different item), the boundary auto-resets and tries again. When the user clicks Retry, `resetErrorBoundary` clears the error state and the Suspense boundary re-tries its async render.
+
+See `suspense-patterns` for the full Suspense discipline; this skill focuses on the error half of the pair.
+
+## Next.js App Router Conventions
+
+The App Router gives error boundaries first-class file conventions:
+
+| File | Scope | What it catches |
+|---|---|---|
+| `app/<segment>/error.tsx` | Route segment | Errors during rendering of that segment's `page.tsx` or any descendant Server/Client component; receives `error` and `reset` props |
+| `app/global-error.tsx` | Root layout fallback | Errors that escape every `error.tsx` — including errors in the root layout itself |
+| `app/<segment>/not-found.tsx` | Route segment | `notFound()` calls — special case of error, distinct UI |
+
+`error.tsx` must be a Client Component (it uses state for the reset action) and is implicitly wrapped in a route-segment-level error boundary. The convention pairs with `loading.tsx` (Suspense fallback) and produces the canonical "fast page with skeleton, then content with error-recovery if something breaks" pattern without manual boundary wiring.
+
+Important constraint: `error.tsx` only catches errors from *its descendant tree*, not from its sibling layout. An error in `app/layout.tsx` escapes the page's `error.tsx` and only `global-error.tsx` can catch it.
+
+## Reporting Caught Errors
+
+A caught error is still an error. Wire every boundary to external reporting:
+
+```tsx
+<ErrorBoundary
+  FallbackComponent={ErrorFallback}
+  onError={(error, info) => {
+    Sentry.captureException(error, { contexts: { react: { componentStack: info.componentStack } } })
+  }}
+>
+  <App />
+</ErrorBoundary>
+```
+
+`info.componentStack` is React's stack trace of which components were rendering when the error occurred — crucial for diagnosis, distinct from the JavaScript stack trace.
+
+Sentry's `@sentry/react` provides a built-in `<Sentry.ErrorBoundary>` that handles reporting automatically. The discipline applies regardless of tool: caught errors must surface somewhere developers see them. A boundary without reporting is a UX feature with no signal-back loop. See `error-tracking` for the broader observability discipline this skill plugs into.
+
+## Common Anti-Patterns
+
+| Anti-pattern | Why it's wrong | Fix |
+|---|---|---|
+| Single app-root boundary, no finer scopes | Any error blanks the whole app | Layer boundaries: app-root + route-segment + feature |
+| Boundary that swallows the error without reporting | Silent UI degradation | Wire `onError` / `componentDidCatch` to Sentry or equivalent |
+| Trying to catch event-handler errors with a boundary | Boundary doesn't catch async/imperative errors | Local `try/catch` in the handler, surface to state via `setError`, re-throw during render |
+| Boundary at the same level as the failing component | A throw during the boundary's own render escapes the boundary | Boundary must be *above* the failing component in the tree |
+| `error.tsx` placed in the wrong route segment | Errors in `app/layout.tsx` aren't caught by `app/page/error.tsx` | Place `error.tsx` at the segment that owns the failing render; use `global-error.tsx` for the root layout |
+| ErrorBoundary inside Suspense (when goal is "failure replaces loading state") | Loading state lingers after fetch fails | Put ErrorBoundary outside Suspense for the common case |
+| Function-component error boundary attempt | Hooks API has no `useErrorBoundary` (as of React 19) | Use a class component or the `react-error-boundary` library |
+| Reset that doesn't actually retry the failed work | User clicks "Retry" but the same stale error state persists | Use `resetKeys` tied to the inputs that should retry, or `resetErrorBoundary` from `react-error-boundary` |
+
+## Verification
+
+After applying this skill, verify:
+
+- [ ] Every route segment with risk of render-time failure has an `error.tsx` (or equivalent boundary).
+- [ ] Every boundary has an `onError` / `componentDidCatch` that reports to external observability.
+- [ ] Event-handler errors and async errors are caught locally and surfaced via state, not assumed to hit the boundary directly.
+- [ ] Error boundary placement matches failure-blast-radius: app-root for catastrophic, route-segment for navigational, feature-level for partial.
+- [ ] When pairing with Suspense, the nesting order matches the desired failure-mode UI (ErrorBoundary outside Suspense for the common case).
+- [ ] Reset path actually retries the failed work — `resetKeys` are tied to inputs that change on retry.
+- [ ] `global-error.tsx` exists as the app-root backstop.
+- [ ] The class-component requirement is acknowledged — no failed attempt to write a function-component boundary without a library.
+
+## Grounding Sources
+
+- React docs — [Catching rendering errors with an error boundary](https://react.dev/reference/react/Component#catching-rendering-errors-with-an-error-boundary). The official reference for `getDerivedStateFromError` and `componentDidCatch`.
+- React legacy docs — [Error Boundaries](https://legacy.reactjs.org/docs/error-boundaries.html). The original explanation from React 16; still the clearest statement of what boundaries do and don't catch.
+- Vaughn, B. / Dodds, K. C. — [`react-error-boundary`](https://github.com/bvaughn/react-error-boundary). The de facto library; reset semantics and `FallbackComponent` API.
+- Next.js docs — [`error.tsx`](https://nextjs.org/docs/app/api-reference/file-conventions/error) and [`global-error.tsx`](https://nextjs.org/docs/app/api-reference/file-conventions/error#global-errorjs). Route-segment boundary conventions.
+- Sentry — [React Error Boundary integration](https://docs.sentry.io/platforms/javascript/guides/react/features/error-boundary/). The observability-pairing pattern.
+- Dodds, K. C. — [Use react-error-boundary to handle errors in React](https://kentcdodds.com/blog/use-react-error-boundary-to-handle-errors-in-react). Composition patterns and reset strategies.
+
+## Do NOT Use When
+
+| Instead of this skill | Use | Why |
+|---|---|---|
+| Suspense boundary placement (loading states, streaming) | `suspense-patterns` | suspense-patterns owns the loading-state mechanism; this skill owns the failure-state mechanism. They pair but are distinct primitives. |
+| Setting up the observability SDK (Sentry init, breadcrumbs, sampling) | `error-tracking` | error-tracking owns the SDK and infrastructure; this skill owns the in-tree React boundary that feeds caught errors into the SDK. |
+| Try/catch discipline in async code (event handlers, promises, await) | `code-review` (or general async error patterns) | Async errors are outside React's call stack — they need local handling first, then re-throwing into render to reach the boundary. |
+| Backend error response design (HTTP status codes, error envelope format) | `api-design` | api-design owns the wire format for backend errors; this skill handles client-side errors after the response. |
+| Server Component error handling (server-side render failure) | `server-components-design` | Server-side rendering errors are caught by `error.tsx` files at the route segment level — a Next.js convention, technically distinct from React's render-phase error boundary. |

package/marketplace/skills/error-tracking/SKILL.md

@@ -0,0 +1,261 @@
+---
+name: error-tracking
+description: "Use when designing or extending an application exception-reporting pipeline: error boundary placement, tracker SDK wrappers, sanitized reporting calls, environment gating, user context without PII leaks, breadcrumbs, and verification that each layer reports correctly. Covers component, route, global, and manual capture surfaces plus central `reportError`/`reportMessage` patterns. Do NOT use for the visual error UX shown to users (use `a11y` and interaction skills), chasing one captured error (use `debugging`), or broad privacy and retention policy (use `owasp-security`)."
+license: MIT
+compatibility: "Tracker-agnostic. The patterns target any exception-reporting SDK with a `captureException` / `captureMessage` / `addBreadcrumb` shape — Sentry, Rollbar, Bugsnag, Honeybadger, Datadog Errors, Application Insights. Examples are framed in React + Next.js because that is the most common surface; analogous primitives exist in Vue (`errorCaptured`), Svelte (error stores), Remix (`ErrorBoundary`), Nuxt (`error.vue`), and any framework with framework-level error hooks."
+allowed-tools: Read Grep Bash Edit
+metadata:
+  metadata: "{\"schema_version\":6,\"version\":\"1.0.0\",\"type\":\"capability\",\"category\":\"engineering\",\"domain\":\"engineering/observability\",\"scope\":\"portable\",\"owner\":\"skill-graph-maintainer\",\"freshness\":\"2026-05-06\",\"drift_check\":\"{\\\\\\\"last_verified\\\\\\\":\\\\\\\"2026-05-06\\\\\\\"}\",\"eval_artifacts\":\"present\",\"eval_state\":\"unverified\",\"routing_eval\":\"absent\",\"stability\":\"experimental\",\"keywords\":\"[\\\\\\\"error tracking\\\\\\\",\\\\\\\"exception reporting\\\\\\\",\\\\\\\"error reporting\\\\\\\",\\\\\\\"error boundary\\\\\\\",\\\\\\\"React ErrorBoundary\\\\\\\",\\\\\\\"route error boundary\\\\\\\",\\\\\\\"global error boundary\\\\\\\",\\\\\\\"error tracker SDK\\\\\\\",\\\\\\\"Sentry integration\\\\\\\",\\\\\\\"captureException wrapper\\\\\\\",\\\\\\\"captureMessage wrapper\\\\\\\",\\\\\\\"addBreadcrumb wrapper\\\\\\\",\\\\\\\"set user context error\\\\\\\",\\\\\\\"PII sanitization error payload\\\\\\\",\\\\\\\"environment-aware error reporting\\\\\\\",\\\\\\\"dev logger prod tracker\\\\\\\",\\\\\\\"error digest deduplication\\\\\\\",\\\\\\\"catastrophic failure capture\\\\\\\",\\\\\\\"reportError wrapper\\\\\\\",\\\\\\\"error tracking provider\\\\\\\"]\",\"examples\":\"[\\\\\\\"set up exception reporting for a new React + Next.js application\\\\\\\",\\\\\\\"add a route-level error boundary that recovers gracefully and still reports\\\\\\\",\\\\\\\"the error tracker is showing customer emails in event payloads — fix the PII leak\\\\\\\",\\\\\\\"wrap captureException in a centralized reporter that adds environment gating\\\\\\\",\\\\\\\"audit the error pipeline — confirm every layer eventually reaches the tracker\\\\\\\",\\\\\\\"decide where error boundaries should live: component, section, route, or app-global\\\\\\\",\\\\\\\"implement PII sanitization for error payloads before they hit the tracker SDK\\\\\\\",\\\\\\\"set user context (internal id, org id, role) on errors without sending email or name\\\\\\\"]\",\"anti_examples\":\"[\\\\\\\"design accessible error-message copy and recovery UI for the 404 page\\\\\\\",\\\\\\\"the boundary fired but the tracker shows no event — root-cause it\\\\\\\",\\\\\\\"explain our error-tracking architecture in the contributor docs\\\\\\\",\\\\\\\"review this AI-generated error handler for correctness\\\\\\\",\\\\\\\"decide if the new error path needs an integration regression test\\\\\\\",\\\\\\\"design our overall PII storage and retention policy across the system\\\\\\\",\\\\\\\"refactor the error-helper module for clarity\\\\\\\"]\",\"relations\":\"{\\\\\\\"boundary\\\\\\\":[{\\\\\\\"skill\\\\\\\":\\\\\\\"debugging\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"debugging chases an observed failure already in the tracker; error-tracking designs the pipeline that captures and routes failures in the first place\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"owasp-security\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"owasp-security owns the cross-cutting PII and credential-handling policy; error-tracking owns the request-time sanitization that error payloads pass through before leaving the application\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"a11y\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"a11y owns the user-visible error UX (message copy, focus management, screen-reader announcements); error-tracking owns the engineering pipeline behind the error boundary\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"refactor\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"refactor reorganizes existing code while preserving behavior; error-tracking changes the *behavior* of the error pipeline (where it reports, what it sanitizes, how layers compose)\\\\\\\"}],\\\\\\\"related\\\\\\\":[\\\\\\\"debugging\\\\\\\",\\\\\\\"owasp-security\\\\\\\",\\\\\\\"a11y\\\\\\\",\\\\\\\"code-review\\\\\\\",\\\\\\\"testing-strategy\\\\\\\"],\\\\\\\"verify_with\\\\\\\":[\\\\\\\"code-review\\\\\\\",\\\\\\\"testing-strategy\\\\\\\"]}\",\"portability\":\"{\\\\\\\"readiness\\\\\\\":\\\\\\\"scripted\\\\\\\",\\\\\\\"targets\\\\\\\":[\\\\\\\"skill-md\\\\\\\"]}\",\"lifecycle\":\"{\\\\\\\"stale_after_days\\\\\\\":90,\\\\\\\"review_cadence\\\\\\\":\\\\\\\"quarterly\\\\\\\"}\",\"skill_graph_source_repo\":\"https://github.com/jacob-balslev/skill-graph\",\"skill_graph_protocol\":\"Skill Metadata Protocol v5\",\"skill_graph_project\":\"Skill Graph\",\"skill_graph_canonical_skill\":\"skills/error-tracking/SKILL.md\",\"skill_graph_export_description\":\"shortened for Agent Skills 1024-character description limit; canonical source keeps the full routing contract\",\"skill_graph_canonical_description_length\":\"1045\"}"
+  skill_graph_source_repo: "https://github.com/jacob-balslev/skill-graph"
+  skill_graph_protocol: Skill Metadata Protocol v4
+  skill_graph_project: Skill Graph
+  skill_graph_canonical_skill: skills/error-tracking/SKILL.md
+---
+
+# Error Tracking
+
+## Coverage
+
+- The four error-capture surfaces every application has, whether by design or accident: component-level boundaries, route-level fallbacks, application-global crash handler, and manual reporting from non-UI code paths
+- The centralized-wrapper pattern: a thin module (`reportError`, `reportMessage`, `addBreadcrumb`, `setUser`, `clearUser`, `isErrorTrackingEnabled`) that sits between application code and the tracker SDK
+- PII sanitization before any external send: a `sanitizePII()` pass over every payload, the rule that internal IDs are sent and email / name / phone are not, and the verification that wrapper-time sanitization is the actual scrubber (not the tracker SDK's `beforeSend`, which is a backstop at best)
+- Environment-aware gating: dev mode emits to a local logger, production emits to the tracker; the gate is a single function so testing is trivial
+- User context: setting and clearing `userId`, `orgId`, `role` (or equivalent) at session boundaries; the object signature versus positional-arg trap
+- Error breadcrumbs: how to add navigation, network, and state context to events without leaking sensitive data
+- Diagnostic discipline: the question *"does this layer actually report, or does it only log?"* — most route-level fallbacks log locally and never reach the tracker unless wired up explicitly
+- Catastrophic-failure path: app-global handler bypasses the wrapper and goes straight to the SDK because the wrapper itself may have failed
+
+## Philosophy
+
+Most production applications develop an error-tracking architecture by accident, one try/catch at a time. The accumulated result is unprincipled: some errors reach the tracker with full PII, some are silently swallowed, some are double-reported (once by the boundary, once by the catch), and the dev-prod gating is per-call instead of central. The first time someone has to audit it — usually after a customer reports their email appearing in a third-party error dashboard — the cost of repair is enormous because every call site has to be revisited.
+
+The discipline is to *centralize*. Application code never imports the tracker SDK directly; it imports a thin wrapper module. The wrapper owns three concerns: sanitization, environment gating, and signature stability. Sanitization runs on every payload before any external call. Environment gating decides whether the call goes to a local logger or to the tracker SDK. Signature stability means the wrapper's API does not change when the underlying tracker is swapped — application code is insulated from vendor decisions.
+
+The second principle is *layering*. Errors arrive through multiple surfaces and each layer is responsible for a different recovery story. Component boundaries catch render-time and effect-time exceptions in a subtree and show a fallback UI. Route boundaries catch errors in a specific route and let other routes keep working. The application-global handler catches everything else and shows a "something went wrong" screen. Manual reporting handles errors caught in non-UI code (background jobs, server actions, async event handlers). Each layer must report — the question to verify on every change is *"does this layer's catch path actually call the wrapper, or does it only log locally?"* The default for many framework-provided fallbacks is the latter.
+
+The third principle is *internal IDs only*. The tracker is operated by a third party. Even with a strict DPA, sending email addresses or names is a privacy escalation that has no justification — internal user and org IDs are sufficient to identify the affected account and let an engineer query application logs for the rest. PII appears in error payloads usually as a side effect of "let's just dump the request body" — `sanitizePII()` is the single chokepoint that catches this.
+
+## The Four Error-Capture Surfaces
+
+```
+Surface 1: Component-level boundary
+  React `ErrorBoundary` / Vue `errorCaptured` / Svelte error store
+  Catches render-time and effect-time exceptions in the subtree
+  Path: catch -> sanitize -> wrapper -> dev logger or tracker
+
+Surface 2: Route-level boundary
+  Next.js `error.tsx` / Remix `ErrorBoundary` / Nuxt `error.vue`
+  Catches per-route errors and shows route-scoped recovery UI
+  Path: framework hook -> shared fallback component -> wrapper
+  (Many framework-provided fallbacks ONLY log locally; verify they call the wrapper)
+
+Surface 3: Application-global crash handler
+  Next.js `global-error.tsx` / framework-equivalent root handler
+  Catches anything that escaped the route layer
+  Path: bypasses wrapper and calls tracker SDK directly
+  (The wrapper itself may have failed; rely only on the SDK at this layer)
+
+Surface 4: Manual reporting (non-UI paths)
+  Background jobs, server actions, async handlers, queue workers
+  Path: try / catch -> wrapper.reportError(error, { tags, extra })
+```
+
+When extending or auditing the architecture, walk all four surfaces. The most common gap is Surface 2 — a route fallback shipped that renders a recovery UI but never calls `reportError`, so the production tracker shows zero events for that route while users see "something went wrong."
+
+## The Centralized Wrapper
+
+The wrapper module is small. Six functions cover most needs:
+
+```typescript
+// error-tracker.ts
+
+import { tracker } from 'your-tracker-sdk';
+import { sanitizePII } from './pii-sanitizer';
+import { logger } from './logger';
+
+const enabled = isProductionEnv() && hasTrackerDsn();
+
+export function isErrorTrackingEnabled(): boolean {
+  return enabled;
+}
+
+export function reportError(
+  error: Error | string,
+  context?: { tags?: Record<string, string>; extra?: unknown; level?: 'fatal' | 'error' | 'warning' }
+): void {
+  const sanitized = context?.extra ? sanitizePII(context.extra) : undefined;
+
+  if (!enabled) {
+    logger.error(error, { ...context, extra: sanitized });
+    return;
+  }
+
+  tracker.captureException(error, {
+    tags: context?.tags,
+    contexts: sanitized ? { sanitized } : undefined,
+    level: context?.level ?? 'error',
+  });
+}
+
+export function reportMessage(
+  message: string,
+  context?: { tags?: Record<string, string>; extra?: unknown; level?: 'info' | 'warning' | 'error' }
+): void {
+  const sanitized = context?.extra ? sanitizePII(context.extra) : undefined;
+
+  if (!enabled) {
+    logger[context?.level ?? 'info'](message, { ...context, extra: sanitized });
+    return;
+  }
+
+  tracker.captureMessage(message, {
+    tags: context?.tags,
+    contexts: sanitized ? { sanitized } : undefined,
+    level: context?.level ?? 'info',
+  });
+}
+
+export function setUser(user: { userId?: string; orgId?: string; role?: string } | null): void {
+  if (!enabled) return;
+  tracker.setUser(user);
+}
+
+export function clearUser(): void {
+  if (!enabled) return;
+  tracker.setUser(null);
+}
+
+export function addBreadcrumb(
+  category: string,
+  message: string,
+  data?: unknown,
+  level?: 'info' | 'warning' | 'error'
+): void {
+  const sanitized = data ? sanitizePII(data) : undefined;
+  if (!enabled) {
+    logger.debug(`[breadcrumb:${category}] ${message}`, sanitized);
+    return;
+  }
+  tracker.addBreadcrumb({ category, message, data: sanitized, level: level ?? 'info' });
+}
+```
+
+Every application code path uses these functions; nothing imports the tracker SDK directly *except* the application-global crash handler (which is the one place where the wrapper itself may have crashed).
+
+## PII Sanitization
+
+`sanitizePII()` is the chokepoint. It is the *only* point at which payloads are scrubbed; the tracker SDK's `beforeSend` hook is a backstop, not the primary defence. Wrapping at the SDK level alone misses everything that flows through `breadcrumb` and `extra` outside the exception flow.
+
+```typescript
+// pii-sanitizer.ts (sketch)
+const PII_KEY_PATTERNS = [
+  /^email$/i, /^e_mail$/i,
+  /^phone$/i, /^phone_number$/i,
+  /^name$/i, /^first_name$/i, /^last_name$/i, /^full_name$/i,
+  /^address$/i, /^street$/i, /^postal_code$/i,
+  /^ssn$/i, /^tax_id$/i,
+  /token/i, /secret/i, /password/i, /api_key/i,
+];
+
+export function sanitizePII(value: unknown, depth = 0): unknown {
+  if (depth > 6) return '[max-depth]';
+  if (value === null || value === undefined) return value;
+  if (typeof value !== 'object') return value;
+  if (Array.isArray(value)) return value.map(v => sanitizePII(v, depth + 1));
+
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(value)) {
+    if (PII_KEY_PATTERNS.some(re => re.test(k))) {
+      out[k] = '[redacted]';
+    } else {
+      out[k] = sanitizePII(v, depth + 1);
+    }
+  }
+  return out;
+}
+```
+
+The patterns and the recursion bound are workload-specific; tune to your domain. The non-negotiable property is that *every* path into the wrapper passes through `sanitizePII` — there is no "trusted" call site.
+
+## User Context
+
+User context is set at the moment a session is established and cleared on sign-out. The signature is an object, not positional arguments — positional args break silently when one of the optional fields shifts position.
+
+```typescript
+// On sign-in or session restore
+setUser({
+  userId: session.user.id,
+  orgId: session.user.orgId,
+  role: session.user.role,
+});
+
+// On sign-out
+clearUser();
+```
+
+What goes in: stable internal identifiers (UUIDs, role enums). What does *not* go in: email, full name, phone, IP address, anything that could identify a real person to a tracker operator who already has their own customer database.
+
+For a multi-tenant application, the `orgId` is essential — it scopes the error to a specific customer organization, lets you query "show me all errors for tenant X," and makes incident response actually possible. Without `orgId`, every error event is anonymous and a tenant-affecting bug looks like a fleet-wide problem.
+
+## Environment-Aware Gating
+
+The gating decision lives in one place: `isErrorTrackingEnabled()`. Two conditions: production-equivalent environment *and* tracker DSN configured. If either is missing, every wrapper call falls through to the local logger.
+
+```typescript
+function isProductionEnv(): boolean {
+  return process.env.NODE_ENV === 'production';
+}
+
+function hasTrackerDsn(): boolean {
+  return Boolean(process.env.TRACKER_DSN ?? process.env.SENTRY_DSN ?? process.env.ROLLBAR_TOKEN);
+}
+```
+
+The benefit is that *every test* exercises the same wrapper and the same sanitization path as production, except the final hop hits a logger instead of a tracker. Tests can assert on logger output to verify what *would* have been sent. Without this gating, tests either use a mock tracker (which drifts from production behavior) or skip the path entirely (which means PII leaks slip through CI).
+
+## Diagnostic Discipline
+
+The single most useful question when auditing or extending the architecture:
+
+> *"Does this layer actually call the wrapper, or does it only log locally?"*
+
+Many framework-provided error fallbacks render a recovery UI and call a console-level logger but never report the event externally. From a user perspective the recovery feels graceful; from an operator perspective the production tracker shows zero events for that route, and a regression that fires the boundary 1000 times an hour is invisible.
+
+The audit:
+
+1. List every error-capture surface in the application (the four-surface model above).
+2. For each surface, find the actual code path: which file owns the catch, what does it do with the error?
+3. Confirm each path calls `reportError` (or, for Surface 3, the SDK directly with sanitization).
+4. For surfaces that only log: decide whether they *should* report, and wire them up if so.
+
+A common output of this audit: "47 routes have `error.tsx` files; 12 of them inherit a shared fallback that does report; 35 inherit a different shared fallback that only logs; we have been blind to errors on those 35 routes for a year."
+
+## Evals
+
+This skill ships a comprehension-eval artifact at [`examples/evals/error-tracking.json`](https://github.com/jacob-balslev/skill-graph/blob/main/examples/evals/error-tracking.json). The checklist below is the authoring gate for exception-reporting pipeline decisions; the eval file is the grader surface.
+
+## Verification
+
+- [ ] All application code reports errors through the wrapper module; nothing imports the tracker SDK directly except the application-global crash handler
+- [ ] Every wrapper call passes payloads through `sanitizePII` before any external send
+- [ ] User context uses internal IDs (`userId`, `orgId`, `role`); no email, name, phone, or address
+- [ ] `isErrorTrackingEnabled()` is the single environment gate; dev mode falls through to the local logger
+- [ ] Component boundaries (Surface 1) catch and call the wrapper
+- [ ] Route fallbacks (Surface 2) explicitly call the wrapper — verify, do not assume
+- [ ] Application-global handler (Surface 3) calls the SDK directly with its own sanitization (the wrapper may have crashed)
+- [ ] Non-UI code (Surface 4) wraps async paths in try/catch and calls `reportError`
+- [ ] Breadcrumbs are added at meaningful state transitions (route change, network call, mutation), with sanitization
+- [ ] At least one regression test exercises a forced error and asserts the wrapper was called with sanitized data
+- [ ] At least one regression test exercises an unconfigured environment and asserts the wrapper falls through to the logger
+
+## Do NOT Use When
+
+| Use instead | When |
+|---|---|
+| `a11y` | Designing accessible error-message copy, focus management on the recovery UI, or screen-reader announcements |
+| `debugging` | Root-causing a single observed error already captured in the tracker |
+| `documentation` | Writing the contributor-docs page that explains the error-tracking architecture |
+| `code-review` | Reviewing an AI-generated error handler for correctness |
+| `testing-strategy` | Deciding whether a new error path warrants an integration regression test |
+| `owasp-security` | Designing the broader PII storage, retention, and credential-handling policy across the system |
+| `refactor` | Reorganizing the error-helper module while preserving its current behavior |