SKUNK-1029 Document by_ref exception for shell rule S1481 (#5952)

* Document by_ref exception for shell rule S1481

Add exception to S1481 shell rule documenting that variables passed by
reference to functions containing 'by_ref' in their name are considered
used. This prevents false positives when variables are passed as plain
word arguments to functions that modify them indirectly.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* Use "Special Cases" rather than exception

This is not exactly an exception, we still check that it is used, but in another way.

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: romainbrenguier

rules/S1481/shell/rule.adoc

@@ -1,5 +1,17 @@
 include::../rationale.adoc[]
 
+=== Special Cases
+
+Variables passed by reference to functions whose name contains `by_ref` are considered used. In bash, some functions accept variable names as plain word arguments (not `$var` expansions) and modify them indirectly. When such a function name contains `by_ref`, word arguments matching declared variable names are counted as legitimate usages.
+
+[source,bash]
+----
+function process_data() {
+  local result status  # Compliant: result and status are used by reference
+  get_values_by_ref result status
+}
+----
+
 include::../how-to-fix-it.adoc[]
 
 === Code examples