pathname: document EagerInitializeExtension rationale

Explain why the module exists (shape cache warning) and the
contract for adding/removing lazy memoised ivars on `Pathname`
or its mixed-in extensions, per review feedback.

Author: p-linnane

Library/Homebrew/extend/pathname/eager_initialize_extension.rb

@@ -1,6 +1,11 @@
 # typed: strict
 # frozen_string_literal: true
 
+# Eagerly initialises {Pathname}'s lazy memoised ivars so every instance
+# shares one object shape, avoiding Ruby's shape-variation warning.
+#
+# Any new `@x ||= ...` ivar added to {Pathname} or its mixed-in extensions
+# must also be added to `#initialize` below to keep the shape stable.
 module EagerInitializeExtension
   extend T::Helpers