groundwork-method 0.0.1 → 0.11.0

package/src/engineer-skills/groundwork-go-engineer/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: groundwork-go-engineer
+description: >
+  Implement and review Go service changes using self-contained engineering
+  references and the current repository as the source of truth. Use for Go
+  backend handlers, services, providers, domain models, migrations, telemetry,
+  structured logging, dependency injection, tests, concurrency, or service
+  architecture. This skill is the execution router for Go backend work: it loads
+  reference docs selectively, preserves core/edge boundaries and the inward
+  dependency rule, coordinates with adjacent skills, and verifies changes
+  against contracts and tests. Use this
+  skill whenever the user works in a Go service directory or asks about Go
+  backend behavior, even if they do not explicitly ask for a "go engineer."
+---
+
+# Go Engineer
+
+Go backend execution router for service repositories. Durable engineering guidance lives in `references/`; this skill decides what to load, how to route the task, what repository facts to verify, and which safety gates apply.
+
+## Operating Contract
+
+1. Load reference docs from `references/` for architectural and implementation guidance. Treat the current repository's code, specs, and generated contracts as the source of truth for naming, structure, and behavior.
+2. Orient with the repo map and Serena before reading widely (see Required First Checks) — find the hubs, then navigate by symbol. Inspect the current repository before naming packages, commands, import paths, schemas, or generated files.
+3. Load the smallest reference set that explains the task. Add more context only when the task crosses a boundary.
+4. Preserve the service's dependency direction and public contracts. Code implements OpenAPI, database migrations, event schemas, and documented architecture — it does not invent them.
+5. Treat observability as part of the contract, not an afterthought: a critical path emits an unbroken trace, and a missing span is a defect. Route durable engineering policy to the canonical docs (`docs/principles/stack/go/`, and the cross-cutting canon under `docs/principles/quality/` and `docs/principles/foundations/`) rather than restating it in code comments or this skill.
+6. Coordinate with adjacent skills when another skill owns the primary decision surface.
+
+---
+
+## Code intelligence (repo map + Serena)
+
+GroundWork gives you a deterministic **repo map** (`npx groundwork-method repo-map` — tree-sitter import edges + PageRank centrality, cached to `.groundwork/cache/repo-map.json`) and the **Serena** MCP server (LSP-backed symbol navigation and editing), registered at init. Orient before reading widely: refresh the map, read its `centrality` ranking to find the hubs, then use Serena to navigate them (`get_symbols_overview` / `find_symbol` / `find_referencing_symbols`) and make reference-aware edits (`replace_symbol_body` / `rename`). Full workflow and the graceful-degradation contract live in `.groundwork/skills/code-intelligence.md`; fall back to ordinary reads and edits when they are unavailable.
+
+---
+
+## Required First Checks
+
+Before non-trivial Go implementation or review work:
+
+| Check | Why |
+|---|---|
+| **Orient with the repo map + Serena** — refresh `npx groundwork-method repo-map`, read its `centrality` ranking to find the hubs, then navigate them with Serena (`get_symbols_overview` / `find_symbol` / `find_referencing_symbols`) | A blind file crawl misses the structure the map already computed; symbol navigation and reference-aware edits beat grep-and-read. Fall back to ordinary reads only when these are unavailable |
+| Service package layout and nearby examples for the touched layer | Prevents inventing structure that already has a convention |
+| `go.mod` for Go and dependency versions | Avoids version-specific advice that contradicts the project |
+| OpenAPI spec (if HTTP behavior changes) | HTTP contracts are generated — code must match the spec |
+| Database schema file + migration tooling (if schema changes) | Schema is target-state — migrations derive from it |
+| Event specs (AsyncAPI, Protobuf, etc.) for async/real-time behavior | Event types drive code generation downstream |
+
+---
+
+## Context Routing
+
+Load only the rows relevant to the current task. Reference files are in the skill's `references/` directory.
+
+| Task shape | Reference to load |
+|---|---|
+| Any non-trivial service change | `architecture.md`, `implementation-patterns.md`, `go-services.md` |
+| Go idioms, context, interfaces, DI, errors, config validation | `go-services.md` |
+| Concurrency, goroutine lifecycle, errgroup, context cancellation | `concurrency.md` |
+| Layer placement, new boundary, dependency direction | `architecture.md` |
+| Capability interface + provider (LLM etc.), generated adapter shape, bare-interface bet, `add-capability` | `capability-ports.md`, `architecture.md` |
+| HTTP endpoint, handler, idempotency, CORS | `http-handlers.md`, `api-design.md` |
+| Database repository, SQL, declarative schema, test isolation | `postgres.md` |
+| Observability — tracing, structured logging, metrics | `observability.md` |
+| Reliability — retries, timeouts, graceful shutdown, backpressure | `reliability-performance.md` |
+| Performance — latency budgets, load shedding, profiling | `reliability-performance.md` |
+| Events, Pub/Sub, WebSocket, async integration | `integration-realtime-data.md` |
+| Tests, quality gates, coverage strategy, flake triage | `testing.md` |
+| Code quality, naming, simplicity, deletion | `code-craft-security.md` |
+| Security, auth, secrets, input validation, supply chain | `code-craft-security.md` |
+| Doc comments, naming-as-documentation, godoc, comment-is-a-smell | `documentation.md` |
+
+---
+
+## Skill Handoffs
+
+Use the smallest collaborating set. Keep the Go engineer as lead when the work is mainly Go implementation inside a service directory.
+
+| Condition | Hand off to |
+|---|---|
+| Endpoint shape, OpenAPI, error envelope, pagination, idempotency, SDK generation, webhooks, versioning | API architect / API design skill |
+| Schema, migrations, indexes, query plans, constraints, RLS, retention, vector/full-text search | Database / Postgres design skill |
+| Streaming, Pub/Sub, WebSockets, event schemas, replay, fan-out, idempotency, source-aware updates | Real-time / event architecture skill |
+| Test strategy, CI quality gates, contract tests, flake reduction, validation design | Test architecture skill |
+| Deployment, Cloud Run, Terraform, Docker, CI/CD, observability infrastructure, local dev tooling | Platform engineering skill |
+
+If the collaborating skill does not exist in the project, handle the concern inline but flag it as outside this skill's primary scope.
+
+---
+
+## Execution Checklist
+
+1. **Identify the touched contract surface** — domain behavior, HTTP contract, database schema, event contract, operational behavior, or tests.
+2. **Load minimal routed references** and inspect nearby code before designing.
+3. **State important inferences** when guidance comes from general Go knowledge rather than project-specific docs or code.
+4. **Implement within existing conventions** — do not create new layer boundaries without evidence from docs or existing code.
+5. **Run targeted tests/checks** when feasible. If not feasible, explain the blocker and name the exact command to run later.
+6. **Summarize** references consulted, files changed, verification performed, and residual risks.
+
+---
+
+## Safety Gates
+
+These constraints prevent the most common classes of architectural damage in Go services.
+
+### Naming and Boundaries
+- Do not invent package paths, command names, contract files, or service boundaries. Verify them in the repository first.
+- Do not create new layer boundaries without evidence from docs or existing code.
+
+### Layer Discipline
+- Do not put business decisions in handlers, edge implementations, middleware, migrations, or generated code when the architecture expects them in domain/service code.
+- Do not leak implementation-specific types across the core/edge boundary. If a database driver type appears in a core interface, the architecture is broken.
+- Always validate configuration at startup (e.g., `envconfig`); do not scatter `os.Getenv` throughout the codebase.
+
+### Inbound Defenses & API Standards
+- Do not use offset/limit pagination for collections; enforce cursor-based pagination.
+- Do not allow mutating endpoints (POST/PATCH) without an `Idempotency-Key` implementation to prevent duplicate side-effects.
+- Do not omit inbound concurrency limits (load shedding); shed load rather than queuing indefinitely.
+- Never use wildcard CORS (`AllowedOrigins: []string{"*"}`).
+
+### Error Handling
+- Do not log and return the same error at multiple layers. Wrap errors with context and log at the boundary established by existing code.
+
+### Concurrency
+- Do not launch untracked goroutines. Verify cancellation, error collection, and shutdown behavior for every concurrent operation.
+
+### Contract & Data Integrity
+- Do not change HTTP behavior without checking the OpenAPI source and any generated-client workflow.
+- Do not change database behavior without checking the target-state schema, the migration workflow, and dry-run output when feasible. Use declarative schemas.
+- Do not add or modify domain event types without updating the corresponding event spec.
+
+### Generation
+- Do not run code generation manually outside documented generation flows.
+
+---
+
+## Quick Reference
+
+Frequently needed patterns. Verify against the actual repository before using them.
+
+### Domain Error Pattern
+
+| Sentinel pattern | HTTP mapping | Use |
+|---|---|---|
+| `ErrNotFound` | 404 | Resource lookup miss |
+| `ErrUnauthorized` | 401 | Missing or invalid auth |
+| `ErrForbidden` | 403 | Valid auth, insufficient permission |
+| `ErrConflict` | 409 | Duplicate resource |
+| `ErrPayloadTooLarge` | 413 | File exceeds size/duration limit |
+| `ErrInvalidFormat` | 415 | Input format validation failure |
+| `ErrValidation` (catch-all) | 422 | Field-level validation failures |
+
+### Mock Pattern
+
+Hand-written mocks with settable `Func` fields. Read the mock file before writing tests — function signatures often include parameters easy to miss from the interface alone.
+
+### Event Broadcast Pattern
+
+Domain mutations broadcast via an event hub in service methods. For testing, use a mock event hub and assert captured events. Async events use a transactional outbox pattern.
+
+### Idempotency Middleware
+
+Caches responses by key + user ID. For tests, implement an in-memory repository rather than depending on the production store.
+
+---
+
+## Output Expectations
+
+- Name the references or source files that informed non-obvious decisions.
+- Separate verified repository facts from recommendations based on general Go knowledge.
+- Provide concrete verification commands and results.
+- For code reviews: findings first, ordered by severity, with file references and missing-test risks.
+- For implementation work: changed files, behavior, tests, and follow-up risks.

package/src/engineer-skills/groundwork-go-engineer/references/api-design.md

@@ -0,0 +1,82 @@
+# API Design
+
+## Core Principles
+
+### 1. Contract-First, Code-Generated
+
+Specs live in `/specs` and are the source of truth. Server handlers, typed clients, and reference docs are generated from them. Write the spec before the handler. Hand-rolled clients drift; generated clients cannot.
+
+### 2. Explicit Versioning, Additive Evolution
+
+Breaking changes require a new major version and a documented deprecation window. Within a major version, evolve additively: new optional fields, new endpoints, new response codes. Existing clients must never break from schema extension.
+
+### 3. Resources, Not RPCs
+
+HTTP endpoints model resources (`POST /entities`, `GET /entities/{id}`), not verbs (`POST /createEntity`). The resource shape forces identity, lifecycle, and composition reasoning up front. When a verb is unavoidable, name it carefully and document why a resource shape does not fit.
+
+### 4. Idempotency by Design
+
+Every write endpoint accepts an `Idempotency-Key` header. The server stores the key long enough to detect replays; the client is not responsible for being careful.
+
+### 5. Pagination and Filtering Are Uniform
+
+Every collection endpoint paginates with the same cursor shape, filters with the same query-string grammar, and returns the same `next`/`prev` link structure. Inconsistent pagination is a design smell.
+
+### 6. Errors Are Structured and Machine-Readable
+
+Every error response carries a stable code, a human message, and a `details` object. Clients branch on the code, not on the prose. Error codes are catalogued and never renumbered.
+
+### 7. AI-Agent Readability Is a First-Class Concern
+
+OpenAPI specs include rich descriptions on every field, enumerations for every finite domain, and explicit examples on every endpoint. An agent reading the spec should be able to use the API correctly without reading the handler.
+
+### 8. Async Events Are Contracts Too
+
+WebSocket and Pub/Sub events receive the same rigour as HTTP — AsyncAPI spec, generated client and server models, additive evolution.
+
+## Error Envelope (RFC 9457)
+
+All error responses follow this shape:
+
+```json
+{
+  "status": 404,
+  "title": "Not Found",
+  "detail": "No entity with the provided id exists.",
+  "instance": "/entities/abc123"
+}
+```
+
+Validation errors include a field-level `errors` array:
+
+```json
+{
+  "status": 422,
+  "title": "Unprocessable Entity",
+  "detail": "Request body did not match the schema.",
+  "errors": [
+    { "message": "required", "path": "body.title", "value": "" }
+  ]
+}
+```
+
+## Common HTTP Status Codes
+
+| Status | Title | Meaning | Action |
+|---|---|---|---|
+| 401 | Unauthorized | Missing or invalid auth token | Re-authenticate |
+| 403 | Forbidden | Authenticated but not authorised | Confirm role. Do not retry |
+| 404 | Not Found | Resource does not exist | Verify identifier |
+| 422 | Unprocessable Entity | Request body did not match schema | Inspect `errors` array |
+| 409 | Conflict | Idempotency-Key reused with different payload | Generate a fresh key |
+| 429 | Too Many Requests | Rate limit exceeded | Back off per `Retry-After` |
+| 504 | Gateway Timeout | Downstream dependency timed out | Retry with backoff |
+| 500 | Internal Server Error | Unexpected server error | Retry with backoff; escalate if sustained |
+
+## Anti-Patterns
+
+- **Breaking changes without a version bump.** The assumption "no one uses that field" is always wrong.
+- **Hand-written clients.** Clients drift. Generate.
+- **Kitchen-sink endpoints.** Split large payloads into focused endpoints.
+- **Error payloads as strings.** Structured errors, always.
+- **Endpoint-scoped pagination conventions.** Pick one and apply universally.

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

@@ -0,0 +1,42 @@
+# Service Structure: A Pure Core, Swappable Edges
+
+## Dependency Rule
+
+Dependencies flow inward. The core depends on nothing concrete; the edge implementations depend on the core through the interfaces it owns.
+
+## Where code lives
+
+| Zone | Location | Depends on | Contains |
+|---|---|---|---|
+| **Domain** | `internal/core/domain` | Nothing | Entities, value objects, validation, sentinel errors |
+| **Core service** | `internal/core/service` | Domain | Application orchestration **and** the interfaces it consumes (`Repository`, `MessageQueue`, `TextGenerator`) — declared at the point of use, in domain language |
+| **Edge implementations** | technology-named packages — `internal/postgres`, `internal/kafka`, `internal/pubsub`, `internal/httpclient`, `internal/websocket`, `internal/llm` | Domain + `internal/core/service` | Concrete implementations of the core's interfaces (Postgres, Kafka, Pub/Sub, HTTP clients, the LLM client) |
+| **Entrypoints (driving edge)** | `internal/entrypoints` | Domain + Services | HTTP routes, middleware, WebSocket handlers |
+| **Composition root** | `cmd/` | Everything | Wires concrete implementations into services at startup |
+
+The interface and the code that calls it live in the **same** package — Go's "accept interfaces, return structs," applied to the whole service. There is no abstract `adapters` package and no layer named for the pattern; the core is `internal/core/service`, and each implementation sits in a package named for the technology it wraps (`internal/postgres`, `internal/kafka`, …).
+
+## Structural Invariants
+
+- The domain and core service import no framework, no driver, no HTTP library, no SQL client.
+- Interfaces are owned by the core package that consumes them, declared in domain language and named for the role (`Repository`, not `PostgresThing`).
+- Edge implementations are interchangeable — swapping Postgres for another store requires zero core changes. They import `internal/core/service` and assert conformance with `var _ service.Repository = (*Repository)(nil)` (edge → core, the correct inward direction).
+- The application service orchestrates; it does not contain business rules. Rules live on entities.
+- Three conceptual zones: domain; the core service (interfaces + orchestration); edge implementations. More layers are ritual, not rigour.
+
+## Dependency Enforcement
+
+`depguard` is a **shipped gate** in `.golangci.yml.template`: it denies `internal/core/...` importing any edge package (`internal/postgres`, `internal/kafka`, `internal/pubsub`, `internal/httpclient`, `internal/websocket`, `internal/llm`) or any framework/driver, allowing it only stdlib + `internal/core/...`. The edge and the composition root in `cmd/` may import anything. A core-imports-edge violation fails `golangci-lint run`, so the inward-flow rule is a guarantee, not a hope.
+
+## Anti-Patterns
+
+- **Framework-coupled core.** If the core imports `gin.Context` or any HTTP type, it is no longer the core.
+- **Anaemic domain models.** Data structs with no behaviour and a thick service that knows all the rules.
+- **Leaky interfaces.** An interface with `*sql.DB` in its signature is a Postgres type wearing a costume.
+- **Layer-skipping.** Handlers that talk directly to a store because "it is just a simple endpoint."
+- **Per-implementation domain types.** Different entity definitions across packages. Map explicitly at the edge.
+- **Over-layering.** Five layers of DTO translation between HTTP and the core. Edge code is thin.
+
+## Test Seams
+
+A pure core is trivially testable without infrastructure — every outbound dependency is an interface that can be stubbed. Test the edge implementation against the real thing it wraps; test the service against stubs of the interfaces it consumes.

package/src/engineer-skills/groundwork-go-engineer/references/capability-ports.md

@@ -0,0 +1,50 @@
+# Capability Ports & Providers
+
+GroundWork scaffolds external capabilities (LLM inference, and the same pattern for any future capability) as **an interface in the core plus a selectable provider that satisfies it**. When you read or hand-write one of these, match the generated shape exactly — the generator and your code are the same contract.
+
+## The model
+
+- A **capability** is an interface declared by the core that consumes it, in `internal/core/service` (package `service`) — domain-named (e.g. `TextGenerator`), no SDK type in its signature.
+- A **provider** is the vendor that satisfies the capability; its implementation is the adapter, in a technology-named edge package (e.g. `internal/llm`). Choosing a provider selects the implementation wired in at the edge; the interface and its callers never change.
+- Each provider declares a **footprint** — exactly one of `env`, `compose-service`, `runner`, `none` — which is the only thing that varies the operational cost. Infrastructure is a consequence of the provider, not a default.
+
+| Footprint | Means | Materializes as |
+|---|---|---|
+| `env` | config only (a hosted API) | env vars in `.env`, no infra |
+| `compose-service` | a container (a self-hosted server) | a service in `docker-compose.yml` |
+| `runner` | a host process | an entry in `.dev/dev.config.json` runners |
+| `none` | the bare interface — a bet | interface + stub + conformance test, nothing else |
+
+## Generated shape (LLM reference family)
+
+```
+internal/core/service/llm.go      # the interface — declared where it is consumed, domain-owned
+internal/llm/llm.go               # the adapter — one provider's implementation
+internal/llm/llm_test.go          # the contract test
+```
+
+- **Interface** — a plain interface in `package service`, no SDK or HTTP type in its signature. An interface with `*sql.DB` or an `*http.Client` in it is an implementation wearing a costume.
+  ```go
+  // internal/core/service/llm.go
+  package service
+
+  type TextGenerator interface {
+      GenerateText(ctx context.Context, prompt string, maxTokens int) (string, error)
+  }
+  ```
+- **Adapter** — `package llm`, implemented with `net/http` and stdlib, no vendor SDK (so `go.mod` is untouched and the adapter compiles standalone). Reads its config from `os.Getenv`, retries transient 5xx/429/connection failures, maps non-retryable status to a permanent error. It imports `internal/core/service` and asserts conformance at compile time (edge → core, the inward direction):
+  ```go
+  var _ service.TextGenerator = (*Client)(nil)
+  ```
+- **Wiring** — construct `llm.NewClient()` in `cmd/api/main.go` and pass it, typed as the `service.TextGenerator` interface, into your service. Run `go mod tidy` if a provider added a dependency. Never let a service depend on the concrete `*llm.Client`.
+
+## The `none` bare interface (a bet)
+
+`--provider none` ships the interface, a stub adapter that returns a not-implemented error, and a contract test that `Skip`s while the stub errors and flips to a live assertion once `GenerateText` works. Go has no xfail, so the skip *is* the open-bet marker: a green suite with a visible skip means "the contract is fixed, the implementation is owed." Implement the adapter behind the existing interface to cash it — do not touch the interface or the test's conformance line.
+
+## Rules when you touch one of these
+
+- Add a capability to an existing service with `nx g add-capability --service <svc> --capability llm --provider <p>` — it runs the same injector the scaffold does, idempotently.
+- Swapping providers swaps only the adapter file and the footprint. If a change forces the interface or a caller to change, the interface was leaky — fix the interface, not the callers.
+- Surfaces and frontends do **not** embed an adapter; they call this service's interface over its API (keys stay server-side, one owner per capability).
+- A hand-written adapter must pass the same `var _ service.X = (*T)(nil)` conformance assertion and the contract test the generator emits.

package/src/engineer-skills/groundwork-go-engineer/references/code-craft-security.md

@@ -0,0 +1,34 @@
+# Code Craft & Security
+
+## Code Craft Principles
+
+1. **Simpler is better than clever.** Plain data structures over clever abstractions, plain control flow over meta-programming.
+2. **No speculative abstraction.** Three concrete use cases before generalising.
+3. **Deletion is a virtue.** Dead code cannot break, confuse, or leak.
+4. **Names are the interface.** Spend time on names. Rename aggressively.
+5. **Comments explain the "why."** Non-obvious constraints, invariants, ADR references.
+6. **Error handling is design, not decoration.** Decide which errors a function returns, how callers respond, where recoverable/fatal boundary is.
+7. **Trust the boundary; distrust the internal.** Validate at system boundaries. Do not re-validate between internal callers.
+8. **Dead code is a bug.** Commented-out code, `_unused` variables, orphan functions — delete them.
+
+## Security Principles
+
+1. **Zero trust between services.** Every call carries an identity, every identity is authorised per operation.
+2. **Threat model the change.** Five-minute threat conversation for new endpoints, data fields, integrations.
+3. **Secrets are managed, rotated, and audited.** No secrets in source. Fetched at runtime from a secret manager.
+4. **Input is hostile; validate at the boundary.** Request bodies, webhook payloads, message queue events.
+5. **Supply chain is part of the attack surface.** Pin versions, review new dependencies, SBOM generation.
+6. **Least privilege by default.** Minimum permissions, extended only on evidence.
+7. **Auth is boring technology.** Standard auth provider, standard session handling. No custom auth.
+8. **Detect and respond, not just prevent.** Log security events, alert on suspicious patterns, run tabletops.
+
+## Anti-Patterns
+
+### Code Craft
+- Defensive programming without a threat model. "Might need it later" scaffolding.
+- Fashion-driven refactors. Multi-paragraph docstrings. Backwards-compatibility shims for internal APIs.
+
+### Security
+- Internal network = trusted. Secrets in environment variables checked into Git.
+- "It is an internal tool, we can skip auth." Dependencies pulled in on intuition.
+- Exotic auth. "The WAF will catch it."

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

@@ -0,0 +1,108 @@
+# Concurrency
+
+## Core Rules
+
+Every goroutine has an owner. `errgroup.WithContext` is the default supervision primitive. Context is passed everywhere. No goroutine runs past the lifetime of the work it was started for.
+
+### Never Use Bare `go func()`
+
+A bare `go func()` that fires and forgets is a goroutine with no owner and no cancellation path. Every `go` statement launches a goroutine that is either:
+
+1. Tracked by an `errgroup.Group` or `sync.WaitGroup` that the caller waits on, or
+2. A long-lived background worker started at program entry and shut down via a dedicated `context.Context` and `sync.WaitGroup` on the composition root.
+
+### `errgroup.WithContext` Is the Default
+
+For fan-out work — fetching multiple resources concurrently, processing items in parallel:
+
+```go
+g, ctx := errgroup.WithContext(ctx)
+
+g.Go(func() error {
+    return fetchResource(ctx, id)
+})
+g.Go(func() error {
+    return fetchMetadata(ctx, id)
+})
+
+if err := g.Wait(); err != nil {
+    return fmt.Errorf("fetching resources: %w", err)
+}
+```
+
+When the first goroutine returns an error, the derived `ctx` is cancelled, signalling the others to stop.
+
+### Context Propagation Is Non-Negotiable
+
+Every function that launches goroutines accepts a `context.Context` and passes it down. Every goroutine checks `ctx.Done()` on any blocking operation:
+
+```go
+select {
+case result := <-ch:
+    process(result)
+case <-ctx.Done():
+    return ctx.Err()
+}
+```
+
+### Limit Concurrency with Semaphores
+
+Unconstrained fan-out exhausts file descriptors and saturates downstream services:
+
+```go
+const maxConcurrency = 10
+sem := make(chan struct{}, maxConcurrency)
+
+g, ctx := errgroup.WithContext(ctx)
+for _, item := range items {
+    sem <- struct{}{}
+    g.Go(func() error {
+        defer func() { <-sem }()
+        return process(ctx, item)
+    })
+}
+if err := g.Wait(); err != nil {
+    return fmt.Errorf("processing items: %w", err)
+}
+```
+
+### Shared State: Channels First, Mutexes Second
+
+Pass ownership via channels rather than sharing pointers through mutexes. Use `sync.Mutex` when a channel would be awkward — e.g., protecting a map read from many goroutines.
+
+Never access shared state without synchronisation. The Go race detector (`-race`) is a required CI gate.
+
+## Graceful Shutdown
+
+Background workers started at program entry respect the root context. The composition root in `cmd/` creates a context cancelled by `SIGTERM`/`SIGINT`:
+
+```go
+func (w *Worker) Run(ctx context.Context) error {
+    for {
+        select {
+        case <-ctx.Done():
+            return nil
+        case job := <-w.queue:
+            if err := w.process(ctx, job); err != nil {
+                // log, metric, continue — or propagate if fatal
+            }
+        }
+    }
+}
+```
+
+The composition root waits on all workers before the process exits. A service that kills itself with `os.Exit` rather than waiting for goroutines to drain drops in-flight requests and corrupts state.
+
+## Anti-Patterns
+
+- **Fire-and-forget goroutines.** If you don't track it, you don't own it.
+- **Sharing context derivations across goroutines.** Each goroutine derives its own from the parent.
+- **Goroutines in `init()` or package-level `var`.** Goroutines belong in functions with explicit lifecycle management.
+- **Infinite retry loops without backoff and cancellation.** A retry loop that ignores `ctx.Done()` spins forever after shutdown.
+- **Mutexes without deferred unlock.** Always `defer mu.Unlock()` immediately after acquiring the lock.
+
+## References
+
+- [sync/errgroup package](https://pkg.go.dev/golang.org/x/sync/errgroup)
+- *The Go Memory Model* (golang.org/ref/mem)
+- *Concurrency in Go*, Katherine Cox-Buday

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

@@ -0,0 +1,130 @@
+# Documentation
+
+Go ships its documentation discipline in the toolchain: `go doc` and pkg.go.dev render doc comments, `gofmt` normalises them, `go vet` flags malformed ones. The language was designed so that well-named code needs little prose around it. Lean on that.
+
+## Hierarchy
+
+Structure documents more reliably than comments. A comment is a promise no compiler checks; when the code changes, the comment silently lies. Documentation priority — the foundations principle (`docs/principles/foundations/documentation.md`) written the Go way:
+
+1. **Types and signatures** — the compiler rejects incorrect types. Zero drift risk.
+2. **Naming** — self-documenting identifiers and small interfaces. Refactor before you comment.
+3. **Error context** — `fmt.Errorf("doing X: %w", err)` strings document the failure path and are exercised by every call site.
+4. **Test names** — `TestReserve_OutOfStock_ReturnsConflict` is executable documentation verified by CI.
+5. **Doc comments on exported API** — rendered by godoc; written only when the signature cannot carry the contract.
+6. **Inline "why" comments** — last resort for a genuinely non-obvious decision.
+
+Levels 1–4 are verified by tooling. Levels 5–6 are human promises that drift. Minimise them.
+
+## Doc Comments
+
+A doc comment is the sentence directly above a declaration, and it begins with the name of the thing it documents — `go doc` and pkg.go.dev parse that convention, and `go vet`'s doc checks rely on it.
+
+```go
+// Reserve holds stock for an order until the reservation expires.
+// It returns ErrOutOfStock when the requested quantity is unavailable.
+func (s *Service) Reserve(ctx context.Context, orderID string, qty int) error
+```
+
+Document the **exported** surface — the package's contract with its callers. Unexported helpers are read with their implementation in view; a doc comment there is usually redundant with the code below it.
+
+State the contract the signature cannot: the error conditions a caller must branch on, side effects invisible in the return type, the units or invariants of a parameter. Do not restate the signature in prose.
+
+```go
+// BAD — restates the signature
+// GetOrder gets an order by id and returns it.
+func GetOrder(ctx context.Context, id string) (*Order, error)
+
+// GOOD — skip it; the name + types already say this
+func GetOrder(ctx context.Context, id string) (*Order, error)
+```
+
+## Package Documentation
+
+A package earns a doc comment when its name does not convey its purpose, its boundaries, or how its pieces fit. Put it in a dedicated `doc.go` so it survives file churn:
+
+```go
+// Package inventory tracks stock levels and reservations.
+//
+// A reservation is a hold with a TTL; a hold that expires returns its
+// quantity to available stock. Callers reserve, then either commit or
+// release — an abandoned hold is reclaimed by the sweeper, not the caller.
+package inventory
+```
+
+The comment orients a reader before they open a single file. A package whose name and exported identifiers already explain it (`httpclient`, `postgres`) needs no `doc.go`.
+
+## Names and Interfaces Are the Documentation
+
+The cheapest documentation is a name that makes the comment unnecessary. Go's conventions push this hard, and the service standards bake them in (`references/go-services.md`): small interfaces defined by their consumer, concrete types returned, no stuttering (`inventory.Service`, not `inventory.InventoryService`).
+
+A one-to-three-method interface documents a capability by its shape:
+
+```go
+// The name and the single method are the whole contract.
+type ReservationStore interface {
+    Save(ctx context.Context, r Reservation) error
+}
+```
+
+A wide interface needs a comment to explain what it is *for* — which is the signal it is doing too much. Narrow it, and the comment disappears.
+
+## Error Messages Are Documentation
+
+A Go error string is read far more often than any doc comment — it surfaces in logs, traces, and incident timelines. Treat it as documentation of the failure path. Wrap with context that names the operation, so the chain reads as a trace:
+
+```go
+if err := store.Save(ctx, r); err != nil {
+    return fmt.Errorf("reserving stock for order %s: %w", orderID, err)
+}
+```
+
+Lowercase, no trailing punctuation, no "failed to" prefix — the convention that lets wraps compose cleanly (`reserving stock for order 7: writing row: connection refused`). Sentinel and structured errors document the branches a caller is expected to take; define them where that caller lives (`references/go-services.md`).
+
+## Inline Comments
+
+Inline comments explain **why**, never **what**. The code already says what it does; the comment captures the reason the next reader cannot recover from the code alone.
+
+```go
+// Sweep every 30s: shorter churns the DB, longer lets expired holds
+// starve available stock past the SLA. Tuned against load test #214.
+ticker := time.NewTicker(30 * time.Second)
+```
+
+A comment that narrates the mechanics is noise — the reader can see the loop.
+
+```go
+// BAD — narrates the obvious
+// loop over the items and sum the quantities
+for _, item := range items {
+    total += item.Qty
+}
+```
+
+## A Comment Is Often a Smell
+
+When you reach for a comment to explain *what* a block does, the code is asking to be refactored. The comment is debt; the fix is in the code:
+
+- A comment explaining a variable → rename the variable.
+- A comment heading a block → extract a function whose name is that comment.
+- A comment decoding a boolean argument (`Process(data, true) // skip cache`) → introduce a named type or option.
+- A comment listing what a function does in three parts → the function does three things; split it.
+
+Delete the comment and fix the name. The refactor cannot drift; the comment can.
+
+## In-Code Markers
+
+```go
+// TODO(bob): batch these writes once the store supports it. Issue #231.
+// FIXME(carol): retry storms under partition; needs a circuit breaker. Issue #245.
+// HACK(dave): upstream returns 200 with an error body; inspect payload until fixed.
+```
+
+Always include `(username)` and an issue reference. A marker without one will never be resolved.
+
+## What NOT to Document
+
+- Self-evident exported functions where the name and types tell the whole story.
+- Unexported helpers read in context with their callers.
+- `Args`/`Returns`-style prose that duplicates the signature — Go has no such convention; the types are the parameter docs.
+- Struct fields whose name and type are clear (`CreatedAt time.Time`); comment only a non-obvious unit or invariant.
+- Generated code (protobuf, mocks) — never hand-edit comments into it.