evals/evals.json
[
{
"id": 1,
"name": "stdlib-first-json",
"description": "encoding/json should be tried first even for high-throughput use cases; third-party libraries are only justified after profiling confirms JSON is the bottleneck",
"prompt": "I'm building a high-throughput Go API that processes thousands of JSON requests per second. A colleague says: 'You should use jsoniter or sonic from the start — encoding/json is known to be slow and you'll need the performance. There's no reason to start with a worse library when we know we'll need the fast one.' Is this advice correct? What JSON library should I use?",
"trap": "The colleague's argument sounds pragmatic — why start with a known-slower library if you'll switch later anyway? But the skill teaches stdlib-first: add dependencies only when profiling confirms they are the bottleneck. The model should push back on the colleague and recommend starting with encoding/json.",
"assertions": [
{"id": "1.1", "text": "Pushes back on the colleague's advice — recommends starting with encoding/json despite the high-throughput context"},
{"id": "1.2", "text": "Explains that the standard library should be the default until profiling confirms JSON is actually the bottleneck"},
{"id": "1.3", "text": "Notes that encoding/json may be sufficient — thousands of requests per second does not automatically justify a third-party library"},
{"id": "1.4", "text": "Recommends profiling first (pprof) before reaching for jsoniter or sonic"},
{"id": "1.5", "text": "If mentioning alternatives (jsoniter, sonic), frames them as options for after measurement proves stdlib is insufficient, not as defaults"}
]
},
{
"id": 2,
"name": "pgx-over-lib-pq",
"description": "Tests whether the model recommends pgx over lib/pq for PostgreSQL when advanced features or performance matter",
"prompt": "I'm starting a new Go project that needs to connect to PostgreSQL. Which driver should I use?",
"trap": "Without the skill, the model recommends lib/pq because it's more commonly seen in tutorials, missing that pgx is faster and has more features",
"assertions": [
{"id": "2.1", "text": "Recommends pgx (github.com/jackc/pgx) as the primary recommendation"},
{"id": "2.2", "text": "Mentions that pgx is faster than lib/pq"},
{"id": "2.3", "text": "Notes that pgx supports all PostgreSQL types and advanced features"},
{"id": "2.4", "text": "May mention lib/pq as an alternative but positions pgx as the preferred choice"},
{"id": "2.5", "text": "Does NOT recommend lib/pq as the primary choice without mentioning pgx"}
]
},
{
"id": 3,
"name": "chi-for-minimal-router",
"description": "Tests whether the model recommends chi for lightweight routing needs instead of full frameworks",
"prompt": "I need a simple HTTP router for my Go REST API. It just needs path parameters and middleware support. I want to stay close to net/http. What should I use?",
"trap": "Without the skill, the model recommends Gin or Echo (full frameworks) when chi's lightweight, net/http-compatible router is a better fit",
"assertions": [
{"id": "3.1", "text": "Recommends chi (github.com/go-chi/chi) as a strong match for the stated requirements"},
{"id": "3.2", "text": "Explains that chi is lightweight and composes well with net/http"},
{"id": "3.3", "text": "Notes that chi has minimal dependencies"},
{"id": "3.4", "text": "May mention Gin/Echo as alternatives but positions chi as the better fit for staying close to net/http"},
{"id": "3.5", "text": "Does NOT recommend a full framework (Gin, Echo, Fiber) as the primary choice when the user explicitly wants to stay close to net/http"}
]
},
{
"id": 4,
"name": "slog-over-external-loggers",
"description": "Tests whether the model considers log/slog (Go 1.21+) before recommending external logging libraries",
"prompt": "I need structured logging in my Go 1.22 project. What library should I use?",
"trap": "Without the skill, the model jumps to zap or zerolog without mentioning that Go 1.21+ has log/slog in the standard library",
"assertions": [
{"id": "4.1", "text": "Mentions log/slog as the standard library option for structured logging (available since Go 1.21)"},
{"id": "4.2", "text": "Presents slog as a viable option, not just an afterthought"},
{"id": "4.3", "text": "If recommending external libraries (zap, zerolog), explains what specific value they add over slog"},
{"id": "4.4", "text": "Does NOT skip standard library consideration entirely"},
{"id": "4.5", "text": "May mention zap/zerolog for specific use cases (zero-allocation hot paths, etc.)"}
]
},
{
"id": 5,
"name": "sqlc-vs-orm-decision",
"description": "Tests whether the model presents sqlc as an alternative to ORMs when the user values type safety and compile-time checks",
"prompt": "I want to interact with my PostgreSQL database in Go. I want maximum type safety and want the compiler to catch SQL errors. What should I use?",
"trap": "Without the skill, the model recommends GORM (most popular ORM) which uses runtime reflection, missing sqlc which generates type-safe code from SQL at compile time",
"assertions": [
{"id": "5.1", "text": "Recommends sqlc (github.com/sqlc-dev/sqlc) as a primary option for compile-time SQL safety"},
{"id": "5.2", "text": "Explains that sqlc generates type-safe Go code from SQL with no runtime reflection"},
{"id": "5.3", "text": "Mentions that GORM uses runtime reflection which does not catch SQL errors at compile time"},
{"id": "5.4", "text": "May also mention ent as a code-generated alternative"},
{"id": "5.5", "text": "Does NOT recommend only GORM when the user explicitly asks for compile-time safety"}
]
},
{
"id": 6,
"name": "rate-limiter-stdlib-first",
"description": "Tests whether the model recommends golang.org/x/time/rate before third-party rate limiters",
"prompt": "I need to add rate limiting to my Go HTTP API. What should I use?",
"trap": "Without the skill, the model recommends a third-party rate limiter without mentioning the official golang.org/x/time/rate package",
"assertions": [
{"id": "6.1", "text": "Recommends golang.org/x/time/rate as the standard/official option"},
{"id": "6.2", "text": "Explains that it implements a token bucket algorithm"},
{"id": "6.3", "text": "May mention third-party alternatives (Tollbooth/limiter) for HTTP middleware integration"},
{"id": "6.4", "text": "Does NOT skip the official x/time/rate package entirely"},
{"id": "6.5", "text": "Explains when third-party middleware might be preferred (e.g., per-IP limiting, distributed rate limiting)"}
]
},
{
"id": 7,
"name": "franz-go-for-kafka",
"description": "Tests whether the model recommends franz-go for Kafka instead of only the legacy sarama client",
"prompt": "I need a Kafka client for my Go application. What library should I use?",
"trap": "Without the skill, the model recommends sarama (the legacy, most commonly referenced Kafka client) instead of franz-go which is modern, higher-performance, and better maintained",
"assertions": [
{"id": "7.1", "text": "Recommends franz-go (github.com/twmb/franz-go) as a primary recommendation"},
{"id": "7.2", "text": "Describes franz-go as modern, high-performance, and feature-complete"},
{"id": "7.3", "text": "Does NOT recommend only sarama without mentioning franz-go"},
{"id": "7.4", "text": "May mention sarama as an alternative but positions franz-go as the preferred modern choice"}
]
},
{
"id": 8,
"name": "check-maintenance-before-recommending",
"description": "Tests whether the model checks maintenance status before recommending a library",
"prompt": "I need a logging library for my Go project. Someone suggested Logrus. Should I use it?",
"trap": "Without the skill, the model recommends Logrus without noting its maintenance status (deprecated in favor of structured logging)",
"assertions": [
{"id": "8.1", "text": "Mentions that Logrus is deprecated or in maintenance mode"},
{"id": "8.2", "text": "Suggests alternatives: log/slog (stdlib), zap, or zerolog"},
{"id": "8.3", "text": "Explains that for new projects, a maintained alternative is preferred"},
{"id": "8.4", "text": "Does NOT unconditionally recommend Logrus without mentioning its deprecation status"},
{"id": "8.5", "text": "Prioritizes maturity and maintenance status in the recommendation"}
]
},
{
"id": 9,
"name": "avoid-unnecessary-wrappers",
"description": "Tests that the model warns against libraries that just wrap stdlib without adding value",
"prompt": "I found a Go library that provides helper functions for HTTP request handling, basically wrapping net/http with slightly more convenient syntax. Should I add it to my project?",
"trap": "Without the skill, the model evaluates only the convenience factor without considering the anti-pattern of wrapping stdlib without real value",
"assertions": [
{"id": "9.1", "text": "Warns against using libraries that wrap standard library functionality without adding meaningful value"},
{"id": "9.2", "text": "Explains that more dependencies increase attack surface and maintenance burden"},
{"id": "9.3", "text": "Recommends evaluating whether net/http itself is sufficient"},
{"id": "9.4", "text": "Mentions the anti-pattern of adding dependencies for marginal convenience"},
{"id": "9.5", "text": "Suggests considering the library's dependency footprint relative to the value it provides"}
]
},
{
"id": 10,
"name": "testcontainers-for-integration",
"description": "testcontainers-go is preferred over shared docker-compose for integration tests because each test gets an isolated, fresh container",
"prompt": "We already have a docker-compose.yml for local development with PostgreSQL and Redis. A teammate says: 'For integration tests, just document that developers should run docker-compose up before running go test -tags=integration. That way we reuse the same infrastructure we already have and don't add a new dependency.' Is this a good approach? What would you recommend instead?",
"trap": "The teammate's approach seems pragmatic — reuse existing infrastructure, avoid adding testcontainers-go as a dependency. The skill teaches testcontainers-go is better for test isolation: each test run gets a fresh container (no state leakage between test runs), tests are fully self-contained (no 'remember to run docker-compose up'), and CI doesn't need to maintain a shared running stack.",
"assertions": [
{"id": "10.1", "text": "Pushes back on the teammate's docker-compose approach — identifies its key problems: shared state between test runs, manual setup requirement, CI complexity"},
{"id": "10.2", "text": "Recommends testcontainers-go as the preferred alternative for programmatic, isolated integration tests"},
{"id": "10.3", "text": "Explains the key advantage: each test suite gets a fresh container spun up and torn down automatically — no state leakage, no manual prerequisites"},
{"id": "10.4", "text": "Notes that testcontainers-go tests are fully self-contained: go test -tags=integration works without any external setup"},
{"id": "10.5", "text": "Acknowledges the dependency cost but frames it as justified by the isolation and reproducibility benefits"}
]
},
{
"id": 11,
"name": "slices-maps-packages-go121",
"description": "Tests whether the model recommends the standard library slices/maps packages (Go 1.21+) instead of external utility libraries for basic operations",
"prompt": "I need utility functions for slice operations in my Go 1.22 project — things like contains, sort, filter, and reverse. What should I use?",
"trap": "Without the skill, the model recommends samber/lo or a similar utility library for basic operations that the standard library slices package already provides since Go 1.21",
"assertions": [
{"id": "11.1", "text": "Recommends the standard library slices package (Go 1.21+) for Contains, Sort, Reverse, and similar operations"},
{"id": "11.2", "text": "Does NOT recommend only external libraries for basic slice operations that slices package covers"},
{"id": "11.3", "text": "May mention samber/lo or similar for functional operations (Map, Filter, Reduce) not in stdlib slices"},
{"id": "11.4", "text": "Distinguishes between operations covered by stdlib (Contains, Sort, Reverse, Compact, BinarySearch) and those requiring external libraries (Map, Filter, GroupBy)"},
{"id": "11.5", "text": "Applies the 'standard library first' principle"}
]
}
]
references/libraries.md
# Top Go Libraries by Category
## Web Frameworks
**Gin** (<https://github.com/gin-gonic/gin>) High-performance HTTP web framework with minimalist API. Up to 40x faster than some alternatives. Great for building REST APIs and microservices.
**Echo** (<https://github.com/labstack/echo>) Minimalist, extensible web framework. Clean middleware system, excellent performance. Good for both REST APIs and traditional web apps.
**Fiber** (<https://github.com/gofiber/fiber>) Express.js-inspired web framework built on Fasthttp. Very fast, easy for Node.js developers transitioning to Go.
**Chi** (<https://github.com/go-chi/chi>) Lightweight, idiomatic router that composes well with net/http. Minimal dependencies, great for smaller projects.
## HTTP Clients
**Resty** (<https://github.com/go-resty/resty>) Simple HTTP and REST client for Go. Inspired by Ruby's rest-client. Great for API consumption with retry support.
**Req** (<https://github.com/imroc/req>) Simple Go HTTP client with "black magic" - less code, more efficiency. Clean API for common operations.
## ORM & Database
**GORM** (<https://github.com/go-gorm/gorm>) Feature-complete ORM library. Developer-friendly, supports associations, hooks, auto-migrations. The most popular Go ORM.
**SQLx** (<https://github.com/jmoiron/sqlx>) Extensions for database/sql that provide convenience while maintaining power. Type-safe, performant query helpers.
**Ent** (<https://github.com/ent/ent>) Entity framework for Go. Code-generated, type-safe ORM with excellent support for complex queries and graph traversals.
**Sqlc** (<https://github.com/sqlc-dev/sqlc>) Generate type-safe Go code from SQL. No runtime reflection, compiler-checked queries.
## Database Drivers
**go-sql-driver/mysql** (<https://github.com/go-sql-driver/mysql>) MySQL driver for Go's database/sql package. Maintained by the Go team, reliable and performant.
**lib/pq** (<https://github.com/lib/pq>) Pure Go PostgreSQL driver. The gold standard for PostgreSQL in Go.
**pgx** (<https://github.com/jackc/pgx>) PostgreSQL driver with advanced features. Faster than lib/pq, supports all PostgreSQL types.
**redis-go** (<https://github.com/redis/go-redis>) Redis client for Go. Cluster support, modern Redis features, well-maintained.
**mongo-go-driver** (<https://github.com/mongodb/mongo-go-driver>) Official MongoDB driver for Go. Supports async operations, transactions (in newer versions).
## Testing
**Testify** (<https://github.com/stretchr/testify>) Sacred extension to the testing package. Assertions, mocking, suite testing. Essential for Go testing.
**gomock** (<https://github.com/uber-go/mock>) Mocking framework for Go interfaces. Widely used, integrates well with testing package.
**go-sqlmock** (<https://github.com/DATA-DOG/go-sqlmock>) SQL mock driver for testing database operations. Test database code without a real database.
**testcontainers-go** (<https://golang.testcontainers.org>) Integration testing with real dependencies in Docker containers. Spin up databases, message queues, etc.
**httptest** (standard library) Testing HTTP servers/clients. Built into Go, no external dependency needed.
## Command Line and Configuration
**Cobra** (<https://github.com/spf13/cobra>) Commander for modern Go CLI applications. Powerful subcommand system, flags, auto-generated docs. Industry standard for CLIs.
**Viper** (<https://github.com/spf13/viper>) Go configuration with fangs. Works with Cobra, supports multiple formats (JSON, YAML, TOML, env).
**urfave/cli** (<https://github.com/urfave/cli>) Simple, fast, fun package for building command line apps. Alternative to Cobra.
**Koanf** (<https://github.com/knadh/koanf>) Lightweight, extensible library for reading config. Support for JSON, YAML, TOML, env, command line.
**env** (from <https://github.com/caarlos0/env>) Parse environment variables into Go structs with defaults. Simple, type-safe, no struct tags.
## Logging
**Zap** (<https://github.com/uber-go/zap>) Fast, structured, leveled logging. Uber's production logger, zero-allocation in hot paths.
**Zerolog** (<https://github.com/rs/zerolog>) Zero-allocation JSON logging. Very fast, simple API, leveled logging.
**Logrus** (<https://github.com/sirupsen/logrus>) Structured logger for Go. Mature, widely-used, plugin architecture. Note: deprecated in favor of structured logging.
## Validation
**validator** (<https://github.com/go-playground/validator>) Go struct validation. Tags-based, extensive validators, cross-field validation.
**ozzo-validation** (<https://github.com/go-ozzo/ozzo-validation>) Fast validation library. Modern alternative for struct validation.
## JSON Processing
**jsoniter** (<https://github.com/json-iterator/go>) High-performance 100% compatible drop-in replacement for encoding/json. Faster JSON parsing.
## Authentication & Authorization
**Casbin** (<https://github.com/casbin/casbin>) Authorization library supporting ACL, RBAC, ABAC. Policy-based access control.
**JWT** (<https://github.com/golang-jwt/jwt>) JSON Web Token implementation for Go. Full-featured, widely-used.
## Caching
**Ristretto** (<https://github.com/dgraph-io/ristretto>) High-performance memory-bound Go cache.
**BigCache** (<https://github.com/allegro/bigcache>) Efficient key/value cache for gigabytes of data. Sharded, optimized for high throughput.
**go-cache** (<https://github.com/patrickmn/go-cache>) In-memory key-value store with expiration. Thread-safe, simple API.
## Rate Limiting
**Tollbooth** (<https://github.com/ulule/limiter>) Rate limiting HTTP middleware. Simple, volume-based limiting, easy to use.
**golang.org/x/time/rate** (<https://golang.org/x/time/rate>) Standard library rate limiter. Token bucket algorithm, well-maintained.
## Concurrency & Goroutines
**Watermill** (<https://github.com/ThreeDotsLabs/watermill>) Event-driven framework for Go. Message streams, event sourcing, CQRS patterns.
**ro** (<https://github.com/samber/ro>) Reactive programming for Go. Event-driven streams with operators for data flow transformation.
## Messaging
**franz-go** (<https://github.com/twmb/franz-go>) Kafka client for Go. Modern, high-performance, feature-complete client with excellent documentation and community support.
**amqp091-go** (<https://github.com/rabbitmq/amqp091-go>) Official RabbitMQ client for Go. Maintained by RabbitMQ team, supports AMQP 0.9.1 protocol.
**NATS.go** (<https://github.com/nats-io/nats.go>) Client for NATS messaging system. Simple, secure, performant communications.
**Temporal Go SDK** (<https://github.com/temporalio/sdk-go>) Durable execution framework for building reliable async applications. Workflows, activities, and long-running processes.
**DBOS** (<https://github.com/dbos-inc/dbos-transact-golang>) Backend framework for Go applications with durable execution, built on PostgreSQL.
## Types and Data Structures
**gods** (<https://github.com/emirpasic/gods>) Go Data Structures - Sets, Lists, Stacks, Maps, Trees, Queues, and much more
**bloom** (<https://github.com/bits-and-blooms/bloom>) Bloom filter implementation. Memory-efficient set membership testing.
**hyperloglog** (<https://github.com/clarkduvall/hyperloglog>) HyperLogLog implementation for Go. Memory-efficient cardinality estimation for large datasets.
**Carbon** (<https://github.com/uniplaces/carbon>) Simple, semantic time library for Go. Time parsing, formatting, manipulation.
**google/uuid** (<https://github.com/google/uuid>) Generate and parse UUIDs. Official Google library, RFC 4122 compliant.
## Database Schema Migration
**golang-migrate** (<https://github.com/golang-migrate/migrate>) Database migration tool. Supports multiple databases, version control for schemas.
**goose** (<https://github.com/pressly/goose>) Database migration tool. SQL or Go migrations, supports multiple databases.
## WebSockets
**gorilla/websocket** (<https://github.com/gorilla/websocket>) WebSocket package for Go. Mature, widely-used, part of Gorilla toolkit.
## gRPC
**grpc-go** (<https://github.com/grpc/grpc-go>) The Go language implementation of gRPC. HTTP/2 based RPC framework by Google.
## GraphQL
**gqlgen** (<https://github.com/99designs/gqlgen>) Go generate based graphql server library. Type-safe, schema-first, code generation.
**graphql-go** (<https://github.com/graphql-go/graphql>) Implementation of GraphQL for Go. Query execution, schema parsing.
## File Watching
**fsnotify** (<https://github.com/fsnotify/fsnotify>) Cross-platform file system watcher for Go. Watch for file changes efficiently.
## Retry Logic
**avast/retry-go** (<https://github.com/avast/retry-go>) Retry mechanism for Go with exponential backoff. Simple, configurable.
## Error Handling
**pkg/errors** (<https://github.com/pkg/errors>) Legacy projects only. Prefer stdlib `errors`, `fmt.Errorf("%w")`, and `errors.Join` for new code; use a structured error library only when you need stack traces or rich context.
**oops** (<https://github.com/samber/oops>) Error handling library with stack traces, hints, and context. Rich error wrapping with type-safe error chains.
## Metrics & Monitoring
**prometheus/client_golang** (<https://github.com/prometheus/client_golang>) Prometheus instrumentation library for Go. Metrics, histograms, counters, gauges.
**opentelemetry-go** (<https://github.com/open-telemetry/opentelemetry-go>) OpenTelemetry Go API and SDK. Distributed tracing, metrics, logs.
## API Documentation
**swag** (<https://github.com/swaggo/swag>) Auto-generate OpenAPI/Swagger specs from Go code annotations. Parses comment-based annotations (`@Summary`, `@Param`, `@Success`, `@Router`, etc.) on handler functions to produce `swagger.json`/`swagger.yaml`. Integrates with Gin (`gin-swagger`), Echo (`echo-swagger`), Fiber (`fiber-swagger`), Chi, and net/http. Supports Swagger 2.0 and OpenAPI 3.x output.
## Dependency Injection
**do** (<https://github.com/samber/do>) Dependency injection library for Go. Simple, runtime DI with service locator pattern and health checks.
**Wire** (<https://github.com/google/wire>) Code-generated dependency injection for Go. Compile-time dependency injection without reflection.
**Dig** (<https://github.com/uber-go/dig>) Dependency injection container for Go. Runtime DI with lifecycle management.
**Fx** (<https://github.com/uber-go/fx>) Application framework for Go. Built on Dig, provides lifecycle management, dependency injection, and observability.
## Functional Programming & Utilities
**lo** (<https://github.com/samber/lo>) A generics-based helper library for Go. Slice, map, and tuple operations with functional programming style.
**mo** (<https://github.com/samber/mo>) Monads and functional programming helpers for Go. Option, Either, Try, and other functional patterns.
## Excel & Spreadsheet
**Excelize** (<https://github.com/qax-os/excelize>) Go library for reading and writing Excel files (XLSX). Supports formatting, charts, and complex spreadsheet operations.
references/stdlib.md
# Standard Library - New & Experimental
The Go standard library continues to evolve with v2 packages and experimental features. **Prefer these over external libraries when available.**
## V2 Packages (API Breaking Changes)
**math/rand/v2** (Go 1.22+) Improved random number generation with better algorithms (ChaCha8, PCG). Auto-seeded, no more rand.Seed() needed.
**encoding/json/v2** (experimental stdlib package behind `GOEXPERIMENT=jsonv2`) Next-generation JSON encoding/decoding. Evaluate deliberately; most production code should keep `encoding/json` unless the project explicitly opts into the experiment.
## New Packages (Promoted from x/exp)
**slices** (Go 1.21+) Generic slice operations: BinarySearch, Clone, Compact, Compare, Contains, Delete, Insert, Replace, Reverse, Sort. Reduces the need for external libraries.
**maps** (Go 1.21+) Generic map operations: Clone, Copy, DeleteFunc, Equal, EqualFunc. Go 1.23+ adds iterator helpers such as All, Collect, Insert, Keys, and Values.
**cmp** (Go 1.21+) Comparison utilities: Compare, Or, Ordered. Used with the slices/maps packages.
**iter** (Go 1.23+) Iterator support for sequences. Enables range-over functions and integrates with slices/maps methods.
**unique** (Go 1.23+) Value canonicalization and interning. Efficient deduplication of comparable values.
**log/slog** (Go 1.21+) Structured logging for the standard library. Alternative to external logging libraries for many use cases.
**weak** (Go 1.24+) Weak references for garbage collection. Useful for caches and observers.
**structs** (Go 1.23+) Structure layout control and introspection.
## golang.org/x (Official Extensions)
**golang.org/x/oauth2** OAuth2 client implementation. Supports multiple providers (Google, GitHub, etc.). Official OAuth2 client.
**golang.org/x/crypto** Additional cryptographic algorithms: bcrypt, blowfish, scrypt, ssh, acme (Let's Encrypt), pbkdf2.
**golang.org/x/net** Network utilities: websocket, context, proxy, trace, http2, ipv4/ipv6, netutil.
**golang.org/x/text** Text processing: encoding, unicode, cases, search, language (language tag parsing and matching).
**golang.org/x/sync** Extended synchronization: errgroup, singleflight, semaphore.
**golang.org/x/sys/cpu** CPU feature detection for architecture-specific optimized code. Use it only when dispatching between measured implementations; prefer portable stdlib code first.