references/shell-debugging.md

# Shell script debugging playbook

Check in order: exact script/interpreter, input arguments, PATH, working directory, permissions, exit status, stderr, environment, quoting, substitutions, traps and cleanup. Avoid `set -x` where commands carry secrets, because trace output may disclose them.

For Bash: `bash -n script.sh` is syntax checking, not an execution test. ShellCheck can catch classes of robustness bugs but not guarantee business logic. For POSIX: `sh -n script.sh` parses with the active `sh`. Test under the target interpreter and representative weird filenames, missing dependencies and partial failures.

When debugging, preserve original semantics and minimize diffs. Keep examples small, reproducible and read-only unless the user authorized a write.

Primary: https://www.shellcheck.net/wiki/ and Bash manual https://www.gnu.org/software/bash/manual/