@cubis/foundry 0.3.71 → 0.3.72

package/workflows/powers/error-ux-observability/POWER.md

@@ -1,160 +1,173 @@
 ````markdown
 ---
 inclusion: manual
-name: "error-ux-observability"
-displayName: "Error UX & Observability"
-description: "Map backend failures to user-friendly messages, implement proper logging levels, and ensure observable error handling"
-keywords:
-  [
-    "error handling",
-    "error messages",
-    "logging",
-    "observability",
-    "user feedback",
-    "failure mapping",
-    "error ux",
-  ]
+name: error-ux-observability
+description: Design error experiences, structured logging, distributed tracing, alerting strategies, and user-facing error handling for production systems.
+license: Apache-2.0
+metadata:
+  author: cubis-foundry
+  version: "3.0"
+compatibility: Claude Code, Codex, GitHub Copilot, Gemini CLI
 ---
 
 # Error UX & Observability
 
-## Overview
+## Purpose
 
-This power helps you translate technical errors into user-friendly messages, implement proper logging for debugging, and ensure errors are observable in production.
+Bridge user-facing error handling and backend observability. Design error experiences that help users recover, while ensuring engineers have the telemetry to diagnose and fix issues quickly.
 
 ## When to Use
 
-- Implementing error handling in repositories/use cases
-- Mapping API errors to UI messages
-- Adding logging to track issues
-- Reviewing error handling code
-- Debugging production issues
-
-## Quick Reference
-
-### Failure to UI Message Mapping
-
-```dart
-// ✅ Map technical errors to user-friendly messages
-String getErrorMessage(Failure failure) {
-  return failure.when(
-    network: () => 'No internet connection. Please check your network.',
-    server: (code, message) {
-      if (code == 401) return 'Session expired. Please login again.';
-      if (code == 403) return 'You don\'t have permission for this action.';
-      if (code == 404) return 'Resource not found.';
-      if (code >= 500) return 'Server error. Please try again later.';
-      return message ?? 'Something went wrong.';
-    },
-    validation: (errors) => errors.values.first,
-    unauthorized: () => 'Please login to continue.',
-    notFound: () => 'Item not found.',
-    unknown: (error) => 'An unexpected error occurred.',
-  );
-}
-```
+- Designing error messages, states, and recovery flows for users
+- Implementing structured logging and error tracking
+- Setting up distributed tracing across services
+- Building alerting strategies that reduce noise
+- Creating error boundaries and fallback UI
+- Debugging production issues with telemetry data
 
-### Logging Levels
+## Instructions
 
-```dart
-// ✅ Use appropriate log levels
-logger.debug('Cache hit for attendance data'); // Development only
-logger.info('User logged in: userId=${user.id}'); // Important events
-logger.warning('API rate limit approaching'); // Potential issues
-logger.error('Failed to sync attendance', error: e, stackTrace: st); // Errors
-logger.fatal('Database corruption detected'); // Critical failures
-```
+### Step 1 — Design User-Facing Errors
 
-### Error Context
-
-```dart
-// ✅ Include context in errors
-try {
-  await repository.submitLeave(leaveRequest);
-} catch (e, st) {
-  logger.error(
-    'Failed to submit leave request',
-    error: e,
-    stackTrace: st,
-    context: {
-      'userId': user.id,
-      'leaveType': leaveRequest.type,
-      'startDate': leaveRequest.startDate,
-    },
-  );
-  rethrow;
-}
+Every error the user sees must answer three questions:
+
+1. **What happened?** (plain language, no stack traces)
+2. **Is it their fault or ours?** (affects tone)
+3. **What can they do next?** (always give an action)
+
+**Error message structure**:
+
+```
+[Title]: Brief description of what went wrong
+[Body]: What happened and why
+[Action]: Clear next step (retry, change input, contact support)
 ```
 
-## Error Handling Patterns
-
-### Repository Layer
-
-```dart
-@override
-Future<Result<Attendance>> submitAttendance(AttendanceRequest request) async {
-  try {
-    final response = await _remoteDataSource.submit(request);
-    return Result.success(response);
-  } on DioException catch (e) {
-    logger.error('Submit attendance failed', error: e);
-    return Result.failure(_mapDioError(e));
-  } catch (e, st) {
-    logger.error('Unexpected error', error: e, stackTrace: st);
-    return Result.failure(Failure.unknown(e.toString()));
+**Good vs Bad error messages**:
+| Bad | Good |
+|-----|------|
+| "Error 500" | "Something went wrong on our end. We're looking into it." |
+| "Invalid input" | "Email address must include @ and a domain (e.g., name@example.com)" |
+| "Network error" | "Couldn't reach the server. Check your connection and try again." |
+| "Null reference exception" | "We couldn't load your profile. Try refreshing the page." |
+
+**Error states in UI**:
+
+- **Inline**: validation errors next to the field that caused them
+- **Toast/snackbar**: transient non-critical errors (auto-dismiss in 5-8s)
+- **Banner**: persistent issues affecting the whole page
+- **Full page**: catastrophic failures with recovery path
+- **Empty state**: data couldn't load — show illustration + retry button
+
+### Step 2 — Implement Error Boundaries
+
+**Frontend**:
+
+- Catch errors at route/feature boundaries, not globally
+- Show fallback UI that lets the user continue elsewhere
+- Log the error with context (component tree, user action, state)
+- Auto-report to error tracking service
+
+**Backend**:
+
+- Return structured error responses:
+
+```json
+{
+  "error": {
+    "code": "PAYMENT_DECLINED",
+    "message": "Your card was declined. Please try a different payment method.",
+    "details": { "reason": "insufficient_funds" },
+    "requestId": "req_abc123"
   }
 }
 ```
 
-### Controller Layer
-
-```dart
-Future<void> submit() async {
-  final prev = state;
-  state = const AsyncLoading();
-  
-  final result = await ref.read(featureRepositoryProvider).submit(request);
-  
-  result.when(
-    success: (data) => ref.invalidateSelf(),
-    failure: (failure) {
-      logger.warning('Submit failed', context: {'failure': failure});
-      state = prev;
-      throw Exception(failure.message);
-    },
-  );
-}
-```
+- Map internal errors to user-safe messages (never expose stack traces, SQL, or internal paths)
+- Include request ID for correlation
+- Use appropriate HTTP status codes (don't 200 everything)
+
+### Step 3 — Structured Logging
+
+**Every log entry should include**:
+
+- Timestamp (ISO 8601, UTC)
+- Level (debug, info, warn, error)
+- Message (human-readable)
+- Request ID / correlation ID
+- Service name and version
+- User ID (if authenticated)
+- Relevant context (input parameters, affected resource)
+
+**Log levels**:
+| Level | When | Example |
+|-------|------|---------|
+| error | Something failed that shouldn't have | Database connection lost |
+| warn | Something unusual but handled | Rate limit approaching |
+| info | Normal business events | User signed up, order placed |
+| debug | Development troubleshooting | Query parameters, cache hit/miss |
+
+**Rules**:
+
+- Never log secrets, passwords, tokens, or PII
+- Use structured format (JSON) for machine parsing
+- Include enough context to diagnose without reproducing
+- Log at the boundary (entry/exit of service calls)
+
+### Step 4 — Distributed Tracing
+
+**Trace propagation**:
+
+- Every request gets a trace ID at the edge
+- Pass trace ID through all service calls (HTTP headers, message metadata)
+- Each service creates spans for its operations
+- Spans include: operation name, duration, status, attributes
+
+**What to trace**:
+
+- HTTP requests (method, path, status, latency)
+- Database queries (operation, table, duration)
+- External API calls (service, endpoint, latency)
+- Queue operations (publish, consume, processing time)
+- Cache operations (hit/miss, key pattern, latency)
+
+### Step 5 — Alerting Strategy
+
+**Alert on symptoms, not causes**:
+
+- DO alert: "Error rate > 1% for 5 minutes"
+- DON'T alert: "CPU > 80%" (that's a dashboard metric, not an alert)
+
+**Reduce noise**:
+
+- Alert on SLO burn rate, not individual errors
+- Group related alerts (one page, not 50)
+- Required for every alert: runbook link, severity, escalation path
+- Review alert fatigue monthly — suppress alerts that never led to action
+
+## Output Format
 
-### UI Layer
-
-```dart
-ref.listen(controllerProvider, (prev, next) {
-  next.whenOrNull(
-    error: (error, _) {
-      final message = error is Failure 
-        ? getErrorMessage(error)
-        : 'An unexpected error occurred';
-      OneSnackbar.error(context, message);
-    },
-  );
-});
 ```
+## Error Handling Design
+[user-facing error strategy]
+
+## Observability Implementation
+[logging, tracing, and metrics setup]
 
-## Logging Best Practices
+## Alerting Rules
+[what triggers alerts and who responds]
+
+## Runbook
+[diagnosis and resolution steps for common errors]
+```
 
-1. **Never log sensitive data** (passwords, tokens, PII)
-2. **Include context** (userId, action, timestamp)
-3. **Use structured logging** (key-value pairs)
-4. **Log at appropriate levels** (debug/info/warning/error/fatal)
-5. **Include stack traces for errors**
+## Examples
 
-## Steering Files
+**User**: "Design error handling for our checkout flow"
 
-- `failure_to_ui.md` - Complete failure-to-message mapping guide
-- `logging_levels.md` - When to use each log level
+**Response approach**: Map all failure modes (payment declined, inventory gone, session expired, network error). Design user-facing messages for each. Implement retry logic for transient errors. Add structured logging at every decision point. Set up alerts on checkout error rate.
 
-## Templates
+**User**: "We can't figure out why requests are slow in production"
 
-- `failure_message_mapper` - Failure to UI message mapper template
+**Response approach**: Add distributed tracing to identify the slow span. Structured logging at service boundaries. Dashboard for p50/p95/p99 latency. Alert on latency SLO burn rate. Runbook for common latency causes.
 ````

package/workflows/powers/error-ux-observability/SKILL.md

@@ -1,158 +1,170 @@
 ---
-name: "error-ux-observability"
-displayName: "Error UX & Observability"
-description: "Map backend failures to user-friendly messages, implement proper logging levels, and ensure observable error handling"
-keywords:
-  [
-    "error handling",
-    "error messages",
-    "logging",
-    "observability",
-    "user feedback",
-    "failure mapping",
-    "error ux",
-  ]
+name: error-ux-observability
+description: Design error experiences, structured logging, distributed tracing, alerting strategies, and user-facing error handling for production systems.
+license: Apache-2.0
+metadata:
+  author: cubis-foundry
+  version: "3.0"
+compatibility: Claude Code, Codex, GitHub Copilot, Gemini CLI
 ---
 
 # Error UX & Observability
 
-## Overview
+## Purpose
 
-This power helps you translate technical errors into user-friendly messages, implement proper logging for debugging, and ensure errors are observable in production.
+Bridge user-facing error handling and backend observability. Design error experiences that help users recover, while ensuring engineers have the telemetry to diagnose and fix issues quickly.
 
 ## When to Use
 
-- Implementing error handling in repositories/use cases
-- Mapping API errors to UI messages
-- Adding logging to track issues
-- Reviewing error handling code
-- Debugging production issues
-
-## Quick Reference
-
-### Failure to UI Message Mapping
-
-```dart
-// ✅ Map technical errors to user-friendly messages
-String getErrorMessage(Failure failure) {
-  return failure.when(
-    network: () => 'No internet connection. Please check your network.',
-    server: (code, message) {
-      if (code == 401) return 'Session expired. Please login again.';
-      if (code == 403) return 'You don\'t have permission for this action.';
-      if (code == 404) return 'Resource not found.';
-      if (code >= 500) return 'Server error. Please try again later.';
-      return message ?? 'Something went wrong.';
-    },
-    validation: (errors) => errors.values.first,
-    unauthorized: () => 'Please login to continue.',
-    notFound: () => 'Item not found.',
-    unknown: (error) => 'An unexpected error occurred.',
-  );
-}
-```
+- Designing error messages, states, and recovery flows for users
+- Implementing structured logging and error tracking
+- Setting up distributed tracing across services
+- Building alerting strategies that reduce noise
+- Creating error boundaries and fallback UI
+- Debugging production issues with telemetry data
 
-### Logging Levels
+## Instructions
 
-```dart
-// ✅ Use appropriate log levels
-logger.debug('Cache hit for attendance data'); // Development only
-logger.info('User logged in: userId=${user.id}'); // Important events
-logger.warning('API rate limit approaching'); // Potential issues
-logger.error('Failed to sync attendance', error: e, stackTrace: st); // Errors
-logger.fatal('Database corruption detected'); // Critical failures
-```
+### Step 1 — Design User-Facing Errors
 
-### Error Context
-
-```dart
-// ✅ Include context in errors
-try {
-  await repository.submitLeave(leaveRequest);
-} catch (e, st) {
-  logger.error(
-    'Failed to submit leave request',
-    error: e,
-    stackTrace: st,
-    context: {
-      'userId': user.id,
-      'leaveType': leaveRequest.type,
-      'startDate': leaveRequest.startDate,
-    },
-  );
-  rethrow;
-}
+Every error the user sees must answer three questions:
+
+1. **What happened?** (plain language, no stack traces)
+2. **Is it their fault or ours?** (affects tone)
+3. **What can they do next?** (always give an action)
+
+**Error message structure**:
+
+```
+[Title]: Brief description of what went wrong
+[Body]: What happened and why
+[Action]: Clear next step (retry, change input, contact support)
 ```
 
-## Error Handling Patterns
-
-### Repository Layer
-
-```dart
-@override
-Future<Result<Attendance>> submitAttendance(AttendanceRequest request) async {
-  try {
-    final response = await _remoteDataSource.submit(request);
-    return Result.success(response);
-  } on DioException catch (e) {
-    logger.error('Submit attendance failed', error: e);
-    return Result.failure(_mapDioError(e));
-  } catch (e, st) {
-    logger.error('Unexpected error', error: e, stackTrace: st);
-    return Result.failure(Failure.unknown(e.toString()));
+**Good vs Bad error messages**:
+| Bad | Good |
+|-----|------|
+| "Error 500" | "Something went wrong on our end. We're looking into it." |
+| "Invalid input" | "Email address must include @ and a domain (e.g., name@example.com)" |
+| "Network error" | "Couldn't reach the server. Check your connection and try again." |
+| "Null reference exception" | "We couldn't load your profile. Try refreshing the page." |
+
+**Error states in UI**:
+
+- **Inline**: validation errors next to the field that caused them
+- **Toast/snackbar**: transient non-critical errors (auto-dismiss in 5-8s)
+- **Banner**: persistent issues affecting the whole page
+- **Full page**: catastrophic failures with recovery path
+- **Empty state**: data couldn't load — show illustration + retry button
+
+### Step 2 — Implement Error Boundaries
+
+**Frontend**:
+
+- Catch errors at route/feature boundaries, not globally
+- Show fallback UI that lets the user continue elsewhere
+- Log the error with context (component tree, user action, state)
+- Auto-report to error tracking service
+
+**Backend**:
+
+- Return structured error responses:
+
+```json
+{
+  "error": {
+    "code": "PAYMENT_DECLINED",
+    "message": "Your card was declined. Please try a different payment method.",
+    "details": { "reason": "insufficient_funds" },
+    "requestId": "req_abc123"
   }
 }
 ```
 
-### Controller Layer
-
-```dart
-Future<void> submit() async {
-  final prev = state;
-  state = const AsyncLoading();
-  
-  final result = await ref.read(featureRepositoryProvider).submit(request);
-  
-  result.when(
-    success: (data) => ref.invalidateSelf(),
-    failure: (failure) {
-      logger.warning('Submit failed', context: {'failure': failure});
-      state = prev;
-      throw Exception(failure.message);
-    },
-  );
-}
-```
+- Map internal errors to user-safe messages (never expose stack traces, SQL, or internal paths)
+- Include request ID for correlation
+- Use appropriate HTTP status codes (don't 200 everything)
+
+### Step 3 — Structured Logging
+
+**Every log entry should include**:
+
+- Timestamp (ISO 8601, UTC)
+- Level (debug, info, warn, error)
+- Message (human-readable)
+- Request ID / correlation ID
+- Service name and version
+- User ID (if authenticated)
+- Relevant context (input parameters, affected resource)
+
+**Log levels**:
+| Level | When | Example |
+|-------|------|---------|
+| error | Something failed that shouldn't have | Database connection lost |
+| warn | Something unusual but handled | Rate limit approaching |
+| info | Normal business events | User signed up, order placed |
+| debug | Development troubleshooting | Query parameters, cache hit/miss |
+
+**Rules**:
+
+- Never log secrets, passwords, tokens, or PII
+- Use structured format (JSON) for machine parsing
+- Include enough context to diagnose without reproducing
+- Log at the boundary (entry/exit of service calls)
+
+### Step 4 — Distributed Tracing
+
+**Trace propagation**:
+
+- Every request gets a trace ID at the edge
+- Pass trace ID through all service calls (HTTP headers, message metadata)
+- Each service creates spans for its operations
+- Spans include: operation name, duration, status, attributes
+
+**What to trace**:
+
+- HTTP requests (method, path, status, latency)
+- Database queries (operation, table, duration)
+- External API calls (service, endpoint, latency)
+- Queue operations (publish, consume, processing time)
+- Cache operations (hit/miss, key pattern, latency)
+
+### Step 5 — Alerting Strategy
+
+**Alert on symptoms, not causes**:
+
+- DO alert: "Error rate > 1% for 5 minutes"
+- DON'T alert: "CPU > 80%" (that's a dashboard metric, not an alert)
+
+**Reduce noise**:
+
+- Alert on SLO burn rate, not individual errors
+- Group related alerts (one page, not 50)
+- Required for every alert: runbook link, severity, escalation path
+- Review alert fatigue monthly — suppress alerts that never led to action
+
+## Output Format
 
-### UI Layer
-
-```dart
-ref.listen(controllerProvider, (prev, next) {
-  next.whenOrNull(
-    error: (error, _) {
-      final message = error is Failure 
-        ? getErrorMessage(error)
-        : 'An unexpected error occurred';
-      OneSnackbar.error(context, message);
-    },
-  );
-});
 ```
+## Error Handling Design
+[user-facing error strategy]
 
-## Logging Best Practices
+## Observability Implementation
+[logging, tracing, and metrics setup]
 
-1. **Never log sensitive data** (passwords, tokens, PII)
-2. **Include context** (userId, action, timestamp)
-3. **Use structured logging** (key-value pairs)
-4. **Log at appropriate levels** (debug/info/warning/error/fatal)
-5. **Include stack traces for errors**
+## Alerting Rules
+[what triggers alerts and who responds]
+
+## Runbook
+[diagnosis and resolution steps for common errors]
+```
 
-## Steering Files
+## Examples
 
-- `failure_to_ui.md` - Complete failure-to-message mapping guide
-- `logging_levels.md` - When to use each log level
+**User**: "Design error handling for our checkout flow"
 
-## Templates
+**Response approach**: Map all failure modes (payment declined, inventory gone, session expired, network error). Design user-facing messages for each. Implement retry logic for transient errors. Add structured logging at every decision point. Set up alerts on checkout error rate.
 
-- `failure_message_mapper` - Failure to UI message mapper template
+**User**: "We can't figure out why requests are slow in production"
 
+**Response approach**: Add distributed tracing to identify the slow span. Structured logging at service boundaries. Dashboard for p50/p95/p99 latency. Alert on latency SLO burn rate. Runbook for common latency causes.