parsing guidelines

Signed-off-by: Brooke Hamilton <45323234+brooke-hamilton@users.noreply.github.com>

instructions/shell.instructions.md

@@ -18,6 +18,7 @@ Instructions for writing clean, safe, and maintainable shell scripts for bash, s
 - Assume scripts are for automation and testing rather than production systems unless specified otherwise
 - Prefer safe expansions: double-quote variable references (`"$var"`), use `${var}` for clarity, and avoid `eval`
 - Use modern Bash features (`[[ ]]`, `local`, arrays) when portability requirements allow; fall back to POSIX constructs only when needed
+- Choose reliable parsers for structured data instead of ad-hoc text processing
 
 ## Error Handling & Safety
 
@@ -37,6 +38,15 @@ Instructions for writing clean, safe, and maintainable shell scripts for bash, s
 - Create reusable functions instead of repeating similar blocks of code
 - Keep the main execution flow clean and readable
 
+## Working with JSON and YAML
+
+- Prefer dedicated parsers (`jq` for JSON, `yq` for YAML—or `jq` on JSON converted via `yq`) over ad-hoc text processing with `grep`, `awk`, or shell string splitting
+- When `jq`/`yq` are unavailable or not appropriate, choose the next most reliable parser available in your environment, and be explicit about how it should be used safely
+- Validate that required fields exist and handle missing/invalid data paths explicitly (e.g., by checking `jq` exit status or using `// empty`)
+- Quote jq/yq filters to prevent shell expansion and prefer `--raw-output` when you need plain strings
+- Treat parser errors as fatal: combine with `set -euo pipefail` or test command success before using results
+- Document parser dependencies at the top of the script and fail fast with a helpful message if `jq`/`yq` (or alternative tools) are required but not installed
+
 ```bash
 #!/bin/bash