From 6e707bb8d7004d85570be97d5bdb8816bccf90c3 Mon Sep 17 00:00:00 2001 From: jnasbyupgrade Date: Fri, 15 May 2026 14:45:37 -0500 Subject: [PATCH] Clarify debug() level scheme: use ranges, not multiples of 10 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Update the `debug()` comment in `lib.sh` to document the intended range-based scheme: 1-9 for high-level script context, 10-19 for per-loop-iteration detail, 20-29 for nesting inside that — with room within each decade to fine-tune without renumbering. The old comment described "multiples of 10" which was inaccurate and misleading. Related changes in pgxntool-test: - `helpers.bash`: test `debug()` now uses `$TESTDEBUG` instead of `$DEBUG` - `SKILL.md`: added advisory debug level distribution check to commit workflow Co-Authored-By: Claude --- lib.sh | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/lib.sh b/lib.sh index ea38665..0979acf 100644 --- a/lib.sh +++ b/lib.sh @@ -60,13 +60,18 @@ array_not_empty() { # Debug function # Usage: debug LEVEL "message" # Outputs message to stderr if DEBUG >= LEVEL -# Debug levels use multiples of 10 (10, 20, 30, 40, etc.) to allow for easy expansion -# - 10: Critical errors, important warnings -# - 20: Warnings, significant state changes -# - 30: General debugging, function entry/exit, array operations -# - 40: Verbose details, loop iterations -# - 50+: Maximum verbosity -# Enable with: DEBUG=30 scriptname.sh +# +# Debug levels use ranges, not strict multiples, to leave room for fine-tuning +# without renumbering. The order of magnitude gives a rough sense of verbosity: +# - 1-9: High-level script context: arguments (1), top-level entry/exit (2-3), +# lower-level helper calls (4-5) +# - 10-19: Per-iteration detail inside loops: exit+status (10), entry (11), +# intermediate results (15) +# - 20-29: Nesting inside loop-level detail +# - Higher ranges follow the same pattern +# +# A non-trivial script with loops should have debug calls in multiple ranges. +# Enable with: DEBUG=15 scriptname.sh debug() { local level=$1 shift