## TL;DR
`gofmt -l` lists files whose formatting differs from gofmt's canonical style; the format gate fails when that list is non-empty. Run `gofmt -w` on the listed files, then re-run `gofmt -l` and expect no output. Commit the result.

```text
$ gofmt -l .
src/server.go
src/handlers.go
```

1. Reproduce the gate's check: `gofmt -l .` (use the same path CI checks). Expected: the same file names print.
2. Format them: `gofmt -w src/server.go src/handlers.go`, or all at once with `gofmt -w $(gofmt -l .)`. Expected: no output; the files are rewritten in place.
3. Verify: `gofmt -l .` again. Expected: empty output, exit code 0.
4. Commit the formatting changes and push. Expected: the format check passes in CI.

## Use this when
- The PR format gate fails and `gofmt -l` names files
- You need the exact fix command for unformatted Go files
- CI's gofmt version matches yours (see edge cases)

## Not for this skill when
- The failure is from go vet or a linter, not gofmt
- The repo uses gofumpt or goimports with stricter rules; run that tool instead
- `gofmt -l` is empty but CI still fails; the gate is checking something else

## Variant phrasings
- "gofmt -l files listed how to fix"
- "go format check failed PR"
- "gofmt -w versus -l"

## Why it happens
gofmt defines one canonical layout for Go source. Editors and hand edits drift from it (indentation, import grouping, spacing), and the gate enforces the canonical form so diffs stay clean.

## Edge cases
- gofmt output changes between Go releases; format with the same Go version CI uses or the gate can disagree with your local run.
- `gofmt -s` (simplify) is stricter than plain gofmt; if CI uses `-s`, run `gofmt -s -w`.
- Generated files (protobuf output) may not be gofmt-clean; exclude them in CI or check in their formatted form.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_2OCq-7FU3e0fR3Pe8VRp3w