groundwork-method 0.0.1 → 0.11.0

package/src/engineer-skills/groundwork-go-engineer/references/go-services.md

@@ -0,0 +1,77 @@
+# Go Service Standards
+
+Go code is boring on purpose. It leans into the standard library, uses interfaces only where they earn their keep, treats errors as values with context, and structures every service as a pure core wrapped by swappable edges — the inward-dependency rule written the Go way.
+
+## Principles
+
+### 1. Standard Library First
+
+`net/http`, `context`, `database/sql` — the standard library is the default. Reach for third-party packages only when the standard library demonstrably cannot do the job. Frameworks that "wrap" the standard library to make it "easier" usually make it harder to reason about.
+
+### 2. A Pure Core, Swappable Edges
+
+Every service is a thin HTTP handler at the edge that extracts and validates inputs, an application service that orchestrates, domain types that hold rules, and interfaces (e.g. `Repository`) declared in the core package that consumes them, with technology-named implementations at the edge. Packages are nested under `internal/` — `internal/core/domain` and `internal/core/service` (the latter holds both the orchestration **and** the interfaces it calls), technology-named edge packages (`internal/postgres`, `internal/kafka`, `internal/pubsub`, `internal/httpclient`, `internal/websocket`, `internal/llm`), and `internal/entrypoints/api` (HTTP edge) — with composition roots in `cmd/`. Exported interfaces declared at the point of use, unexported or concrete edge types returned. `depguard` (in `.golangci.yml.template`) fails the build if `internal/core/...` imports an edge package.
+
+### 3. Errors Are Values with Context
+
+Wrap errors with `fmt.Errorf("doing X: %w", err)` when adding context. Inspect with `errors.Is` and `errors.As` at the boundary. Never `panic` in service code; `panic` is reserved for truly unrecoverable conditions and is recovered only at the HTTP boundary.
+
+Sentinel errors are defined where the caller must branch on them. Structured error types are defined where the caller needs detail.
+
+### 4. Context Is Threaded Everywhere
+
+Every function that does I/O takes a `context.Context` as its first parameter. Cancellation and deadlines are respected. A goroutine that outlives its parent context without explicit opt-in is a bug. `context.Background()` appears only at program entry points and in tests.
+
+### 5. Concurrency Is Simple or Explicit
+
+`go` statements that fire-and-forget are banned. Every goroutine is tracked by a `sync.WaitGroup`, an `errgroup.Group`, or a channel that signals completion. Shared state is accessed through channels by default, through mutexes when a channel would be awkward, and never through silence.
+
+### 6. Interfaces Are Defined by Consumers
+
+Define interfaces in the package that consumes them — "accept interfaces, return structs." A package that defines an interface for its own use is leaking internals. Small interfaces (one to three methods) compose well; wide interfaces are a smell.
+
+### 7. Dependency Injection Is Manual and Explicit
+
+No runtime DI frameworks. Dependencies are passed into constructors. Composition happens in a `cmd/` entry point — the "composition root" pattern. Every dependency is visible at build time; cycles are impossible by construction.
+
+### 8. Configuration Validation at Startup
+
+Validate all environment variables immediately at startup using declarative struct tags (e.g., using `kelseyhightower/envconfig`). Do not scatter `os.Getenv` throughout the codebase. If configuration is missing or invalid, the service must crash immediately before accepting traffic.
+
+```go
+type Config struct {
+    DatabaseURL string `envconfig:"DATABASE_URL" required:"true"`
+    Port        int    `envconfig:"PORT" default:"8080"`
+    Environment string `envconfig:"ENVIRONMENT" default:"production"`
+}
+
+func main() {
+    var cfg Config
+    if err := envconfig.Process("myapp", &cfg); err != nil {
+        log.Fatalf("failed to load configuration: %v", err)
+    }
+    // ...
+}
+```
+
+### 9. Tests Use the Real Thing Where Possible
+
+Service tests spin up a real Postgres container via Testcontainers and exercise the handler through HTTP. Mock only the expensive external edges (model clients, third-party APIs).
+
+## Anti-Patterns
+
+- **Framework-flavoured Go.** Heavy router libraries, ORMs that rewrite queries.
+- **`interface{}` or `any` as a type.** Except at reflection boundaries. Name the type.
+- **Package-level mutable state.** Config, loggers, metrics registries in package variables. Inject them.
+- **Goroutines without supervision.** If you launch it, you own its lifetime.
+- **`init()` functions that do work.** `init` is for registering, not for running.
+- **Pointer-to-struct when a value would do.** Pointers imply "this may be nil or may be mutated." If neither is true, pass the value.
+
+## Canonical References
+
+- *The Go Programming Language*, Donovan & Kernighan
+- *100 Go Mistakes and How to Avoid Them*, Teiva Harsanyi
+- *Dave Cheney's blog* (dave.cheney.net)
+- *Effective Go* (go.dev/doc/effective_go)
+- *Uber Go Style Guide* (github.com/uber-go/guide)
+- *The Go Memory Model* (golang.org/ref/mem)

package/src/engineer-skills/groundwork-go-engineer/references/http-handlers.md

@@ -0,0 +1,172 @@
+# HTTP Handlers
+
+## Handler Framework
+
+Handlers use typed function registration (e.g., Huma v2, Chi, or standard library). The Go types are the spec — no separate YAML to drift from production. Request types are validated before the handler runs. Error responses are serialised to RFC 9457 `application/problem+json`.
+
+## Handler Structure
+
+### Registration
+
+Register every handler via a typed registration function. Pass an operation for metadata and a typed function for implementation:
+
+```go
+func RegisterEntity(api huma.API, svc service.EntityService) {
+    huma.Register(api, huma.Operation{
+        OperationID:   "createEntity",
+        Method:        http.MethodPost,
+        Path:          "/entities",
+        Summary:       "Create an Entity",
+        Tags:          []string{"Entities"},
+        DefaultStatus: http.StatusCreated,
+        Security:      []map[string][]string{{"bearerAuth": {}}},
+    }, func(ctx context.Context, req *CreateEntityRequest) (*CreateEntityResponse, error) {
+        // ...
+    })
+}
+```
+
+Each `RegisterXxx` function takes the API and the service interfaces it needs. Called once from the composition root in `internal/entrypoints/api/router.go`.
+
+### Handler Signature
+
+```go
+func(ctx context.Context, req *InputType) (*OutputType, error)
+```
+
+- `ctx` carries request context, auth principal, and cancellation signal.
+- `req` is fully validated before the function is called.
+- Return `(nil, huma.NewError(...))` to abort with a specific HTTP status.
+- Return `(nil, err)` for unexpected errors — framework converts to a 500.
+
+### Request Types
+
+Request structs compose path, query, header, and body fields with struct tags:
+
+```go
+type CreateEntityRequest struct {
+    IdempotencyKey string `header:"Idempotency-Key" required:"false" format:"uuid"`
+    Body           createEntityBody
+}
+
+type createEntityBody struct {
+    Name  string  `json:"name" min:"1" max:"100" example:"example"`
+    Email string  `json:"email" format:"email"`
+    RefID *string `json:"ref_id,omitempty"`
+}
+```
+
+Use a nested body type (unexported) to separate the JSON body from path/query/header fields.
+
+### Response Types
+
+```go
+type CreateEntityResponse struct {
+    Body EntityItem
+}
+
+type EntityItem struct {
+    ID        string `json:"id" format:"uuid" readOnly:"true"`
+    Name      string `json:"name"`
+    CreatedAt string `json:"created_at" format:"date-time" readOnly:"true"`
+}
+```
+
+Use `readOnly:"true"` on fields never accepted on input. Keep response types separate from request body types.
+
+## Authentication
+
+Extract the principal at the top of the handler:
+
+```go
+func(ctx context.Context, req *GetEntityRequest) (*GetEntityResponse, error) {
+    principal, err := auth.PrincipalFromContext(ctx)
+    if err != nil {
+        return nil, huma.NewError(http.StatusUnauthorized, "unauthorized")
+    }
+    // use principal.ID(), principal.IsSystem(), etc.
+}
+```
+
+Pass the principal into service calls — never access auth state from globals.
+
+## Error Handling
+
+Use framework helpers for expected domain errors; return unwrapped errors for unexpected failures:
+
+```go
+// Domain validation error
+if err := entity.Validate(); err != nil {
+    return nil, huma.NewError(http.StatusUnprocessableEntity, err.Error())
+}
+
+// Auth failure
+return nil, huma.NewError(http.StatusForbidden, "insufficient permissions")
+
+// Unexpected error — framework returns 500
+saved, err := svc.Save(ctx, principal, entity)
+if err != nil {
+    return nil, err  // log at the service layer
+}
+```
+
+Do not log errors in the handler and also return them. Log at the layer with enough context; wrap elsewhere.
+
+## Inbound Defenses
+
+### CORS Configuration
+
+Configure CORS explicitly at the router level. Never use wildcard `"*"` origins in production.
+
+```go
+import "github.com/go-chi/cors"
+
+router.Use(cors.Handler(cors.Options{
+    AllowedOrigins:   []string{"https://app.example.com"}, // Loaded from config
+    AllowedMethods:   []string{"GET", "POST", "PATCH", "DELETE", "OPTIONS"},
+    AllowedHeaders:   []string{"Accept", "Authorization", "Content-Type", "Idempotency-Key"},
+    AllowCredentials: true,
+}))
+```
+
+### Idempotency Middleware
+
+Mutating endpoints (`POST`, `PATCH`) must be idempotent. Extract the `Idempotency-Key` header and verify its state before allowing the handler to execute.
+
+```go
+func IdempotencyMiddleware(store IdempotencyStore) func(http.Handler) http.Handler {
+    return func(next http.Handler) http.Handler {
+        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+            key := r.Header.Get("Idempotency-Key")
+            if key == "" && (r.Method == "POST" || r.Method == "PATCH") {
+                http.Error(w, "Idempotency-Key required", http.StatusBadRequest)
+                return
+            }
+            
+            // Check store and return cached response if COMPLETED,
+            // or 409 Conflict if IN_PROGRESS.
+            // Otherwise, proceed.
+            next.ServeHTTP(w, r)
+        })
+    }
+}
+```
+
+## Handler Placement
+
+- One `RegisterXxx` function per domain resource in `internal/entrypoints/api/routes/<resource>.go`
+- Request/response types in the same file as the handler
+- Domain conversion helpers (`toXxx`) at the bottom of the file, unexported
+- Inline closures for simple handlers; named methods on a struct for handlers that share helpers
+- When a handler needs more than two service calls or substantial conditional logic, move logic to the application service layer
+
+## Operation Metadata
+
+Every operation needs:
+
+- `OperationID` — unique, camelCase, used as the generated client method name
+- `Method` + `Path` — HTTP verb and URI template; use `{id}` placeholders
+- `Summary` — one sentence, title-cased, no period
+- `Tags` — group the endpoint in the OpenAPI UI
+- `Security` — authentication scheme for the endpoint
+- `DefaultStatus` — only for non-200 success codes (201 for creation, 204 for deletions)

package/src/engineer-skills/groundwork-go-engineer/references/implementation-patterns.md

@@ -0,0 +1,156 @@
+# Implementation Patterns
+
+Concrete Go patterns for trace-first logging, a pure core with swappable edges, error handling, and dependency injection.
+
+## 1. Trace-First Development
+
+Every inbound request starts a trace. Every outbound request cascades it.
+
+### Initializing a Span
+
+```go
+import "go.opentelemetry.io/otel/trace"
+
+func (s *OrderService) Process(ctx context.Context, orderID string) error {
+	ctx, span := s.tracer.Start(ctx, "OrderService.Process")
+	defer span.End()
+
+	span.SetAttributes(attribute.String("order.id", orderID))
+	// ... logic
+}
+```
+
+### Passing Context
+
+Context is King. Do not store context in structs. Pass it as the first parameter to every domain, service, and edge-implementation function. Dropping the context severs the distributed trace.
+
+## 2. Error Handling
+
+Use Go's `errors.Is` with sentinel errors to prevent database or HTTP leakage into domain logic.
+
+### Defining Sentinels
+
+Define business rule errors in `internal/core/domain/errors.go`:
+
+```go
+package domain
+
+import "errors"
+
+var ErrNotFound    = errors.New("not found")
+var ErrUnauthorized = errors.New("unauthorized access")
+```
+
+### Wrapping & Mapping Errors at the Edge
+
+An edge implementation catching an infrastructure error wraps it into a Domain error before returning:
+
+```go
+// internal/postgres
+func (r *Repository) Get(ctx context.Context, id string) (*domain.Entity, error) {
+	var entity domain.Entity
+	err := r.db.QueryRowContext(ctx, "SELECT ...").Scan(...)
+
+	if err != nil {
+		if errors.Is(err, sql.ErrNoRows) {
+			return nil, fmt.Errorf("lookup failed: %w", domain.ErrNotFound)
+		}
+		// %v, not %w: unexpected driver errors stay opaque at the storage
+		// boundary so callers cannot couple to infrastructure internals.
+		return nil, fmt.Errorf("unexpected db error: %v", err)
+	}
+	return &entity, nil
+}
+```
+
+## 3. Dependency Injection
+
+### The Interface (Declared by the Core)
+
+The interface belongs in `internal/core/service` (package `service`), declared at the point of use and speaking Domain language:
+
+```go
+package service
+
+import "myservice/internal/core/domain"
+
+type EntityStore interface {
+	Get(ctx context.Context, id string) (*domain.Entity, error)
+}
+```
+
+### The Wiring (Composition Root)
+
+Constructor injection assembles pieces at startup without globals:
+
+```go
+// 1. Initialize the concrete edge implementation
+store := postgres.NewRepository(sqlDB)
+
+// 2. Inject into the Service (which only knows the service.EntityStore interface)
+entityService := service.NewEntityService(store)
+
+// 3. Inject the Service into the inbound HTTP route
+entrypoints.RegisterEntityRoutes(router, entityService)
+```
+
+## 4. Accept Interfaces, Return Structs
+
+This idiom is how the inward-dependency rule is written in Go. The core service declares the interface; it accepts that interface; the edge implementation returns a concrete struct that satisfies it.
+
+```go
+// 1. The interface lives in the core, with the code that calls it
+package service
+
+type Store interface {
+	Get(ctx context.Context, id string) (*domain.Entity, error)
+}
+
+// 2. The Service accepts the interface
+func NewService(store Store) *Service {
+	return &Service{store: store}
+}
+
+// 3. The edge implementation returns the concrete struct
+package postgres
+
+type Repository struct { /* ... */ }
+
+func NewRepository(db *sql.DB) *Repository {
+	return &Repository{db: db}
+}
+```
+
+## 5. Goroutines and Context Loss
+
+When spawning background tasks, use `context.WithoutCancel` (Go 1.21+) or extract/inject the trace so the background span remains a child of the request trace — even if the HTTP client disconnects early.
+
+```go
+func (s *Service) ProcessAsync(ctx context.Context) {
+	bgCtx := context.WithoutCancel(ctx)
+
+	go func() {
+		_, span := s.tracer.Start(bgCtx, "ProcessAsync.Background")
+		defer span.End()
+		// Execute asynchronous domain work...
+	}()
+}
+```
+
+## 6. Immutability in the Domain
+
+When creating methods on Domain entities that calculate or evaluate state rather than modifying it, enforce immutability by exclusively using value receivers:
+
+```go
+package domain
+
+type Order struct {
+	DurationSeconds int
+	Status          string
+}
+
+// CalculateCost uses a value receiver — cannot mutate the Order.
+func (o Order) CalculateCost(rate float64) float64 {
+	return float64(o.DurationSeconds) * rate
+}
+```

package/src/engineer-skills/groundwork-go-engineer/references/integration-realtime-data.md

@@ -0,0 +1,57 @@
+# Integration Patterns
+
+## Principles
+
+1. **Default to async; upgrade to sync when required.** Sync only for inline response values or strict writes.
+2. **Outbox pattern for DB write + event agreement.** Write event to `outbox` table in same transaction; worker relays to broker.
+3. **Every consumer is idempotent.** De-duplication key or idempotent operations (UPSERT, conditional update).
+4. **Retries have policies.** Explicit maximum, backoff curve, dead-letter destination.
+5. **Webhooks verify, sign, and replay.** HMAC signature over payload. Both sides support replay.
+6. **Timeouts are end-to-end budgets.** Allocated from the outermost caller's budget.
+7. **Circuit breakers protect the system.** Open after threshold, fast-fail, probe periodically.
+8. **Every integration has a contract test.** Real signature verification, retry curve, idempotency in CI.
+
+## Anti-Patterns
+
+- Sync chains three deep. Fire-and-forget webhooks. Commit-and-then-publish.
+- Global retry policies. Dead-letter queues as logs.
+
+---
+
+# Real-Time Architecture
+
+## Principles
+
+1. **WebSocket is the default transport.** SSE for one-way server-to-client only. No long-polling.
+2. **Every message carries a sequence number.** Monotonic, per-session. Detect gaps, duplicates, resync.
+3. **Reconnection is the normal case.** Exponential backoff, jitter, resumption token.
+4. **Backpressure is explicit.** Shed, coalesce, or block. Never buffer unbounded.
+5. **Echo suppression is a design concern.** Specified before the first line of code.
+6. **Idempotent handlers.** Same sequence number processed twice has no additional effect.
+7. **Observability is unbroken across the socket.** OTel trace context propagates into the socket.
+8. **Client state is recoverable, not sacred.** Server is the source of truth.
+
+## Anti-Patterns
+
+- Socket as fire-and-forget bus. Per-connection unbounded buffers. Reconnect-then-refetch-everything.
+- Ad-hoc event schemas. Client-side echo reconciliation.
+
+---
+
+# Data Engineering
+
+## Principles
+
+1. **Events are append-only and immutable.** Correction via compensating events.
+2. **Schemas are versioned and evolvable.** Additive new fields; deprecated fields have a deadline.
+3. **Partition keys are chosen deliberately.** Ordering guarantee per partition.
+4. **CQRS where it pays.** Separate read model for complex projections.
+5. **Event sourcing is a tool, not a religion.** Only where change history is the product.
+6. **Data contracts are documented, versioned, and owned.**
+7. **Retention is a design decision.** Decided at creation, enforced by automation.
+8. **Backfills are planned operations.** Rehearsed in staging, measured in production.
+
+## Anti-Patterns
+
+- Silent schema changes. Mutable event logs. Kitchen-sink events table.
+- Backfills without rehearsal. Retention by accident.

package/src/engineer-skills/groundwork-go-engineer/references/observability.md

@@ -0,0 +1,49 @@
+# Observability
+
+## Core Principles
+
+### 1. OpenTelemetry Is the Common Language
+
+Every service emits traces, metrics, and logs through OpenTelemetry SDKs to a single collector. Vendor lock-in at the collector boundary, not inside application code.
+
+### 2. Traces Are the Primary Signal
+
+Given a choice between adding a metric or enriching a trace, enrich the trace. Traces preserve causality; metrics aggregate it away.
+
+### 3. The Three Pillars Are One Pillar
+
+Logs, metrics, and traces are different projections of the same events. A log line includes its trace ID; a metric includes dimensions to pivot back to traces; an exemplar on a metric points directly at the trace that produced it.
+
+### 4. Dashboards Derive from SLOs
+
+Every dashboard starts with the user-journey SLO it supports. Then latency percentiles, error rates, saturation, and traffic. Dashboards derived from SLOs stay useful; dashboards assembled by adding "interesting-looking" graphs drift.
+
+### 5. Trace-Driven Development
+
+Sketch the trace a new feature should produce *before* writing the handler. What spans must exist? What attributes? What parent-child relationships? The instrumentation design shapes the code.
+
+### 6. Assert on Telemetry in Tests
+
+System tests assert that traces are unbroken end-to-end — a missing span is a test failure. Instrumentation is part of the contract, not an optional decoration.
+
+### 7. Logs Are Structured, Sampled, and Contextual
+
+Every log line is structured (JSON), carries its trace ID, and is emitted at an agreed severity. Sample aggressively at debug and info; do not sample errors.
+
+### 8. Cardinality Is a Design Choice
+
+High-cardinality attributes (per-user, per-tenant) are valuable for debugging but expensive in storage. Tag deliberately — high cardinality on traces, lower cardinality on metrics.
+
+## Implementation
+
+- Use `slog` exclusively for structured logging. Always inject `trace_id` and `span_id` from the current context.
+- Every HTTP endpoint and background job must initialize a Root Span.
+- Adapter calls (SQL queries, Pub/Sub publishing) must extract and cascade the span.
+
+## Anti-Patterns
+
+- **Pillar-at-a-time adoption.** "We'll add metrics now, traces later." You will not.
+- **Vendor SDKs in application code.** Application code imports OpenTelemetry; the collector talks to the vendor.
+- **Dashboards without SLOs.** Pretty charts without a question they answer.
+- **Logs-as-debugger.** Using `printf` style logging to trace a single bug. Write a test; add a span.
+- **Cardinality explosions.** Putting a UUID in a Prometheus label.

package/src/engineer-skills/groundwork-go-engineer/references/postgres.md

@@ -0,0 +1,41 @@
+# Postgres
+
+## Principles
+
+1. **Schema design is a design document.** What it represents, identifies, invariants, queries, retention.
+2. **Columns over JSONB for stable shape.** JSONB for varying shape or rarely queried metadata.
+3. **Migrations are additive, reversible, online.** Nullable columns or cheap defaults. Never block on large rewrites.
+4. **Indexes are evidence-based.** Justified by `pg_stat_user_indexes` and `pg_stat_statements`.
+5. **`pgvector` is the vector store.** Operational simplicity over marginal dedicated-DB performance.
+6. **Connection management is explicit.** Deliberate pool sizing, idle timeouts, statement timeouts.
+7. **Query patterns are reviewed.** `EXPLAIN ANALYZE` in PRs for non-trivial queries.
+8. **Backups and retention are not afterthoughts.** Test restores. Retention decided at table creation.
+
+## Target-State Schema Workflow
+
+1. `db/schema.sql` describes the desired final state.
+2. Migrator compares live DB to target using `pg-schema-diff` or equivalent.
+3. `dry-run` prints planned DDL and hazards.
+4. `migrate` applies the plan.
+
+### Safe Schema Changes
+
+- Add nullable columns first, cheap defaults only when safe for table size.
+- Add new tables empty. Add indexes for known access patterns.
+- Avoid renames, drops, type rewrites in same release as consuming code.
+- Multi-release: expand-contract sequencing.
+
+## The persistence boundary
+
+Take the clean break between the core and the store from a narrow, domain-named port plus real-DB tests — never from a generic repository. Idiomatically in Go:
+
+- **Declare the interface where it is consumed, and keep it small.** The service that needs persistence declares an interface naming only the operations it calls (`type OrderStore interface { ByID(ctx, id) (*Order, error); Save(ctx, *Order) error }`), in the domain's language. The Postgres implementation (over `sqlc`/`pgx`) lives in its own package, returns concrete domain structs, and is wired in at the composition root. *"The bigger the interface, the weaker the abstraction"* — never expose the store's full CRUD surface.
+- **No generic `Repository[T]`.** Per-entity queries, SQL, and row mapping differ, so persistence belongs to an interface, not a type parameter — Go's own guidance uses a type parameter only to *relate* multiple values, not when the implementation differs per type. A generic base used only by tests is speculative generality; delete it.
+- **Right-size it.** A thin CRUD endpoint does not need a hand-written port over the query layer — reach for one when a rich aggregate with invariants must stay storage-ignorant, and then it is one port per aggregate root. When query variety grows, add a query/specification type, not more methods.
+- Integration-test the adapter against a real Postgres (see `testing.md`); do not mock it.
+
+## Anti-Patterns
+
+- JSONB-everything. Indexes "just in case." Migrations that lock hot tables.
+- Raw string interpolation. A second database without documented need.
+- A generic `Repository[T]` over the query layer, or an exposed store-shaped CRUD surface — premature generality that leaks the schema into the core.

package/src/engineer-skills/groundwork-go-engineer/references/reliability-performance.md

@@ -0,0 +1,105 @@
+# Reliability
+
+## Core Principles
+
+### 1. SLOs, Not Uptime Percentages
+
+Every significant service defines a Service Level Objective — a per-endpoint or per-user-journey target with latency and success-rate components, measured over a rolling window. "99.9% uptime" is not an SLO; "p95 `POST /entities` < 300ms over 30 days, 99.5% success" is.
+
+### 2. Error Budgets Govern Velocity
+
+The budget implied by the SLO is a spendable resource. Teams spending below budget ship riskier changes. Teams above budget pause feature work and pay down reliability debt.
+
+### 3. Graceful Degradation Is a Design, Not a Hope
+
+Every user-facing feature has a defined behaviour when its downstream fails. Degradation is decided at design time and implemented alongside the happy path.
+
+### 4. Timeouts, Retries, and Circuit Breakers Are Defaults
+
+Every outbound call has a timeout. Every retry has a bounded policy with jitter. Every client has a circuit breaker against its most important downstreams. Defaults are set in a shared library; opting out requires a written reason.
+
+### 5. Isolate Blast Radius
+
+A single tenant, user, or noisy consumer must not degrade the experience for everyone else. Isolate by quota (per-tenant rate limits), by resource (dedicated queues), and by bulkhead (separate worker pools).
+
+### 6. Rehearse Failure
+
+Inject failures routinely — killed pods, degraded networks, slow databases. Every chaos experiment that finds something surprising is worth a year of CI.
+
+### 7. Alerts Fire on User Impact, Not Mechanism
+
+Alert when users are affected — SLO burn rate, error-rate spikes on user journeys — not when a server has 80% CPU.
+
+### 8. Every Incident Teaches a Specific Lesson
+
+Post-incident: blameless postmortem, specific reliability assumption invalidated, specific change proposed. No "be more careful" action items.
+
+## Anti-Patterns
+
+- **"99.999% uptime" as a target.** Five-nines for a non-core service is reckless.
+- **Retries without policies.** Retry-forever is a self-inflicted DDoS.
+- **Mechanism alerts.** Paging on CPU without user-impact signal.
+- **Postmortems that blame humans.** The action item is the system fix.
+- **SLOs nobody tracks.** An SLO without a dashboard and burn-rate alert is theatre.
+
+---
+
+# Performance
+
+## Core Principles
+
+### 1. Latency Is a Budget, Allocated Top-Down
+
+Every user-facing operation starts with a latency budget at the edge. The budget is allocated to downstream hops. Budgeting makes trade-offs explicit.
+
+### 2. Measure Tail Latency, Not Average
+
+p50 is a marketing number. p95 and p99 are what users experience. Design for the tail.
+
+### 3. Pre-Compute, Cache, and Denormalise Deliberately
+
+Each trades complexity for latency. Each earns its keep with data, not intuition.
+
+### 4. Backpressure Is Designed In
+
+Every producer has a bounded queue and a defined behaviour when the queue fills: shed, coalesce, block.
+
+### 5. Load Shedding Protects the System
+
+When saturated, serve fewer requests well. Shed on clearly-defined criteria using inbound concurrency limits.
+
+```go
+import "golang.org/x/sync/semaphore"
+
+var maxInflight = semaphore.NewWeighted(1000)
+
+func LoadSheddingMiddleware(next http.Handler) http.Handler {
+    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+        if !maxInflight.TryAcquire(1) {
+            http.Error(w, "Service Unavailable", http.StatusServiceUnavailable)
+            return
+        }
+        defer maxInflight.Release(1)
+        next.ServeHTTP(w, r)
+    })
+}
+```
+
+### 6. Hot Paths Have No Allocations to Spare
+
+For the hottest inner loops, write allocation-aware code. Every allocation is a GC pause in waiting.
+
+### 7. Profile Before You Optimise
+
+Every non-trivial optimisation starts with a profile. The "obvious" bottleneck is almost always wrong.
+
+### 8. Budgets Are Enforced in CI
+
+Bundle sizes, handler latencies — measured in CI against committed thresholds. Regressions require a reviewed waiver.
+
+## Anti-Patterns
+
+- **Optimising on hunch.** No profile, no optimisation.
+- **Average-as-metric.** p50 is a lie. Use percentiles.
+- **Unbounded queues.** A queue without a max is a latency bomb.
+- **"We will fix performance later."** If you ship slow, users remember slow.