golang-samber-oops

The golang-samber-oops skill provides guidance for implementing structured error handling in Golang applications using the github.com/samber/oops library. It addresses the limitations of standard Go errors by enriching errors with structured metadata, stack traces, machine-readable error codes, user-safe messages, and contextual attributes that persist throughout the call stack. The skill promotes treating errors as structured operational data rather than plain strings, helping developers and on-call engineers diagnose production issues more efficiently while improving observability and error grouping in monitoring platforms.

The skill focuses on the fluent builder pattern used by samber/oops for creating and managing errors. It covers capabilities such as adding structured key-value attributes with `.With()`, attaching service or domain information with `.In()`, categorizing errors with `.Tags()`, defining machine-readable identifiers through `.Code()`, separating public-facing messages from technical details using `.Public()`, and enriching errors with hints, ownership metadata, tenant context, user context, and trace identifiers. It also documents terminal operations including creating new errors, wrapping existing errors, joining multiple errors, and converting panics into errors through recovery helpers. The guidance emphasizes low-cardinality error messages by storing variable values in attributes rather than interpolating them directly into messages.

This skill is intended for Go engineers, backend developers, platform teams, and AI coding agents working on Golang projects that already use or plan to adopt samber/oops. It is especially useful in distributed systems, APIs, microservices, and production environments where structured observability, debugging efficiency, and consistent error reporting are critical. Teams integrating with logging systems, APM platforms, or incident-response workflows can use this skill to standardize error handling practices across services while improving maintainability and operational visibility.