{
  "instruction": "Use custom exception hierarchy with consistent error envelope for all error responses",
  "relevant_when": "Agent builds a Flask API with error handling",
  "context": "All Flask error responses must use the shape {\"error\": {\"code\": \"...\", \"message\": \"...\"}}. Define a base AppError exception class with subclasses (NotFoundError, ValidationError). Register error handlers centrally via register_error_handlers(app) called in create_app(). Route handlers raise exceptions -- they do not manually construct error dicts. The generic Exception handler must log with app.logger.exception() before returning 500.",
  "sources": [
    {
      "type": "file",
      "filename": "skills/flask-best-practices/SKILL.md",
      "tile": "tessl-labs/flask-best-practices@0.2.0"
    }
  ],
  "checklist": [
    {
      "name": "custom-exception-hierarchy",
      "rule": "Agent defines a base AppError exception class and subclasses like NotFoundError and ValidationError (not ad-hoc error dicts in each route)",
      "relevant_when": "Agent implements error handling for a Flask API"
    },
    {
      "name": "consistent-error-shape",
      "rule": "All error responses use the shape {\"error\": {\"code\": \"...\", \"message\": \"...\"}} -- no mix of different error formats across routes",
      "relevant_when": "Agent returns error responses from Flask routes"
    },
    {
      "name": "register-error-handlers",
      "rule": "Error handlers are registered centrally via a register_error_handlers(app) function called inside create_app() -- not scattered across blueprints",
      "relevant_when": "Agent sets up Flask error handling"
    },
    {
      "name": "generic-exception-handler",
      "rule": "A catch-all Exception handler is registered that logs the error with app.logger.exception() and returns a generic 500 response without leaking stack traces or internal details",
      "relevant_when": "Agent handles unexpected errors in Flask"
    },
    {
      "name": "routes-raise-exceptions",
      "rule": "Route handlers raise custom exceptions (raise NotFoundError(...)) rather than manually returning jsonify({'error': ...}), status_code",
      "relevant_when": "Agent handles error cases in Flask route handlers"
    }
  ]
}