{
  "instruction": "Use global exception handling with ProblemDetails for structured, secure API error responses",
  "relevant_when": "Agent builds or modifies an ASP.NET Core API",
  "context": "ASP.NET Core APIs must use a global exception handler (IExceptionHandler or custom middleware) that catches all exceptions and returns RFC 7807 ProblemDetails responses. The handler must never leak stack traces, must log exceptions with structured ILogger calls, and must handle OperationCanceledException gracefully.",
  "sources": [
    {
      "type": "file",
      "filename": "skills/aspnet-error-handling/SKILL.md",
      "tile": "tessl-labs/aspnet-error-handling@0.1.2"
    }
  ],
  "checklist": [
    {
      "name": "global-exception-handler",
      "rule": "Agent registers a global exception handler using IExceptionHandler (ASP.NET 8+) or custom exception middleware. The handler is registered early in the middleware pipeline before routing and authorization.",
      "relevant_when": "Agent sets up ASP.NET Core middleware pipeline or Program.cs"
    },
    {
      "name": "problemdetails-format",
      "rule": "Agent returns error responses in ProblemDetails format (RFC 7807) with Status, Title, Detail, and Instance fields. Content-Type is set to application/problem+json.",
      "relevant_when": "Agent implements error responses in an ASP.NET Core API"
    },
    {
      "name": "custom-exception-types",
      "rule": "Agent defines custom exception types (e.g., NotFoundException, ConflictException, BusinessRuleException) that carry HTTP status codes and error codes, rather than throwing raw Exception or returning error results manually in controllers.",
      "relevant_when": "Agent implements error handling or business logic errors in ASP.NET Core"
    },
    {
      "name": "no-stack-trace-leaks",
      "rule": "Agent never includes stack traces, internal exception messages from unhandled exceptions, or implementation details in production error responses. Generic messages like 'An unexpected error occurred' are used for 500 errors.",
      "relevant_when": "Agent implements error responses for unhandled or unexpected exceptions"
    },
    {
      "name": "structured-logging",
      "rule": "Agent logs exceptions using ILogger with structured parameters (e.g., LogError(exception, 'Message {Param}', value)) rather than string interpolation or Console.WriteLine.",
      "relevant_when": "Agent adds error logging in exception handlers or middleware"
    },
    {
      "name": "cancellation-handling",
      "rule": "Agent handles OperationCanceledException from cancelled requests gracefully — not logged as an error and not returned as a 500 status code. Controller actions accept CancellationToken parameters.",
      "relevant_when": "Agent implements async controller actions or exception handling middleware"
    },
    {
      "name": "validation-errors",
      "rule": "Agent returns model validation errors as 400 Bad Request with ValidationProblemDetails format, consistent with the ProblemDetails shape used by the exception handler.",
      "relevant_when": "Agent configures model validation or API behavior options"
    },
    {
      "name": "status-code-pages",
      "rule": "Agent configures UseStatusCodePages so non-exception error status codes (404 from missing routes, 405 method not allowed) also return ProblemDetails format.",
      "relevant_when": "Agent sets up the ASP.NET Core middleware pipeline"
    }
  ]
}