doc: clarify IWYU workflow

Document the CI wrapper as the reproducible IWYU entrypoint instead of suggesting ad hoc native runs.
Also describe how to handle suspected false positives, explain when local `IWYU pragma` workarounds are appropriate, and add an example rationale to an existing pragma.

Co-authored-by: Hennadii Stepanov <32963518+hebasto@users.noreply.github.com>
Co-authored-by: Daniel Pfeifer <daniel@pfeifer-mail.de>

doc/developer-notes.md

@@ -539,22 +539,32 @@ The generated coverage report can be accessed at `build/coverage_report/index.ht
 The [`include-what-you-use`](https://github.com/include-what-you-use/include-what-you-use) tool (IWYU)
 helps to enforce the source code organization [policy](#source-code-organization) in this repository.
 
-To ensure consistency, it is recommended to run the IWYU CI job locally rather than running the tool directly.
+To reproduce the IWYU CI job locally, run:
+```bash
+env -i HOME="$HOME" PATH="$PATH" USER="$USER" MAKEJOBS="-j1" FILE_ENV="./ci/test/00_setup_env_native_iwyu.sh" ./ci/test_run_all.sh || echo "IWYU failed"
+```
 
 In some cases, IWYU might suggest headers that seem unnecessary at first glance, but are actually required.
 For example, a macro may use a symbol that requires its own include. Another example is passing a string literal
 to a function that accepts a `std::string` parameter. An implicit conversion occurs at the callsite using the
 `std::string` constructor, which makes the corresponding header required. We accept these suggestions as is.
 
-Use `IWYU pragma: export` very sparingly, as this enforces transitive inclusion of headers
-and undermines the specific purpose of IWYU.
+If the provided IWYU CI job still produces a false positive, reduce it to a minimal reproducer and report it upstream.
+
+Use IWYU pragmas sparingly.
+
+Use `IWYU pragma: keep` only as a narrow workaround when needed.
+
+Use `IWYU pragma: associated` only when IWYU cannot infer the intended associated header.
+
+Use `IWYU pragma: export` very sparingly, as this enforces transitive inclusion of headers and undermines the specific purpose of IWYU.
 
 The acceptable cases for using `IWYU pragma: export` are:
 1. Facade headers. For example, see [`compat/compat.h`](/src/compat/compat.h).
 2. Drop-in replacement headers. For example, see [`util/time.h`](/src/util/time.h).
 3. Presenting a complete interface across multiple headers.
 
-A comment explaining the rationale is required for every use of `IWYU pragma: export`.
+For IWYU pragmas, prefer adding a nearby source comment that explains why the annotation is needed.
 
 ### Performance profiling with perf
 

src/node/blockstorage.h

@@ -18,6 +18,8 @@
 #include <streams.h>
 #include <sync.h>
 #include <uint256.h>
+// IWYU incorrectly suggests removing this header.
+// See https://github.com/include-what-you-use/include-what-you-use/issues/2014.
 #include <util/byte_units.h> // IWYU pragma: keep
 #include <util/expected.h>
 #include <util/fs.h>