hierarchical-errors workflow

Verification status (read first)

What is verified independent of the source feedback:

• errors.AsType[E error](err error) (E, bool) is a real Go 1.26.0 stdlib function — confirmed via pkg.go.dev/errors.
• The Go docs explicitly say "For most uses, prefer AsType" over errors.As.
• errors.Is is NOT legacy. It is the stdlib-documented API for sentinel value matching (io.EOF, sql.ErrNoRows, syscall.EXDEV, context.Canceled, your own var ErrFoo = errors.New(...)). See the Go blog: Working with Errors.
• The decision tree and anti-patterns below follow logically from how these three APIs actually behave.

What could NOT be independently verified (treat as reported-by-feedback, not confirmed):

• The hierarchical-errors CLI tool itself could not be found on GitHub, Sourcegraph, pkg.go.dev, or in golang.org/x/tools as of 2026-07-21. The closest public tool is Go's own modernize analyzer (golang.org/x/tools/gopls/internal/analysis/modernize), which uses a -fix flag rather than lint/fix subcommands.
• The legacyerrors analyzer name (used in //nolint:legacyerrors) does not appear in golang.org/x/tools/go/analysis/passes/ or any public repository.
• Every CLI flag, exit code, error message, and the "0% precision" statistic in ./references/cli-and-flags.md is reproduced from the source feedback and could not be checked against a binary.
• The GOEXPERIMENT=jsonv2 prefix on every command is unconfirmed as a requirement of this linter. GOEXPERIMENT=jsonv2 is a real Go experiment, but it gates the JSON v2 proposal — its connection to error linting is unclear. It may be a quirk of the original project (golangci-lint-auto-configure) rather than a hard requirement.

If you have access to the real binary, please verify the claims in ./references/cli-and-flags.md and remove this disclaimer. If the tool does not exist publicly, the decision tree, anti-patterns, and fix-to-zero warning below remain valid for any linter that flags both errors.As and errors.Is — the reasoning is about Go's APIs, not about one specific tool.