Where in a Go service do you allow slog.Error, and where do you require returning the error instead?

## The decision, and who can overrule it "Log at the top, return everywhere else" sounds like a style rule, but it is really an allocation of authority: it decides who is allowed to declare a failure reported, and therefore what the people reading the logs will see. Two constituencies can legitimately push back. The on-call engineer who cannot diagnose an incident from the single record wants more logging lower down. The person paying for log storage, or tuning alerts that count error records, wants less. A lead owns the balance, and should expect to defend it. ## The rule State it in one line so it can be repeated in review: **a function that returns an error does not report it.** Reporting is done once, at the layer where the error stops travelling: - a command or job binary: `main` receives the error from `run() error`, writes one record, exits non-zero - and because `run` returned normally, its deferred cleanup already finished; - a server: the boundary that converts the failure into a response; - a background worker: the top of the goroutine's loop, which has no caller above it. Everything below wraps with `fmt.Errorf("operation: %w", err)`, adding the operation and the identifiers only that layer knows. ## Write the exceptions down A rule with unwritten exceptions is a rule people quietly stop following. Mine are the cases where nothing is returned, so the log call *is* the single report: - a goroutine started with no one waiting on its result; - best-effort work whose failure does not change the outcome; - a retry loop recording the attempts that failed before one succeeded; - an error deliberately discarded in a deferred call. And one hard prohibition that is not negotiable: **no `log.Fatal` outside `main`.** It is `os.Exit(1)` in disguise, it runs no deferred cleanup, and a helper that calls it has decided for every caller, present and future, that the failure is fatal. ## Enforcement that survives turnover Rank the mechanisms by how much human attention they need: 1. **Structural** - confine the logger to the top-level packages. A lower package that wants to log must add an import, and an automated import check can fail the build on it. This is the only mechanism that keeps working when the people who agreed to the rule have moved on. 2. **Automated review signal** - a check for `log.Fatal` and `os.Exit` outside the main package. Cheap, unambiguous, and it catches the expensive failure mode rather than the merely noisy one. 3. **Review checklist** - useful for the judgment calls the tools cannot make, such as whether a wrap message actually says something. 4. **Documentation alone** - the weakest, and worth writing only because it explains the *why* the tools cannot. ## For a library other teams import The bar is higher, and it is worth saying explicitly in the package's own docs: a library that logs is imposing its output on every importer, including one whose process writes structured records to a different destination and one running inside a test. So a shared library returns errors and logs nothing. Where a library genuinely has diagnostics to emit - a retry it recovered from, a cache it rebuilt - the way to expose them is a hook the importer supplies, not a logger the library chose. That is an API decision you cannot walk back once a dozen teams depend on it. ## When on-call pushes back The complaint - "I got one line and it did not tell me enough" - is usually correct as an observation and wrong as a diagnosis. The fixes, in order of preference: wrap at more layers so the chain names each operation; carry structured detail in typed errors the report site unpacks with `errors.As` and attaches to its record; and only then consider whether some part of the system genuinely handles failures internally and therefore deserves its own report site. Reopening the rule to allow logging on the return path costs you the property that makes the log readable - one incident, one record. ## When to bend the rule deliberately There are honest cases for temporarily allowing more. A subsystem being migrated, where the errors it returns are still poorly worded and an incident is more expensive than the noise. A path so rare that the extra records cost nothing and the confidence is worth it. Handle these as time-boxed exceptions with an owner rather than as amendments to the rule, because the failure mode of a convention is not one violation - it is the second team that cites the first as precedent.