{
  "instructions": [
    {
      "instruction": "Run bash scripts/validate.sh <script-path> as the first step before analyzing any script. Never skip this step even if the script looks correct at a glance.",
      "relevant_when": "User asks to validate, review, check, or audit any shell script",
      "why_given": "The validator catches classes of issues (word splitting, POSIX violations, command injection) that are invisible to casual reading."
    },
    {
      "instruction": "For each issue found, show: (a) the problematic code snippet, (b) the issue explanation with ShellCheck code if applicable, (c) the corrected code, (d) why the fix improves the script.",
      "relevant_when": "Reporting validation results to the user",
      "why_given": "The structured four-part format ensures the developer understands the root cause, not just the symptom."
    },
    {
      "instruction": "Treat all errors (exit code 2) as blocking. Do not declare a script valid if errors exist. Warnings (exit code 1) should be fixed but may be explained if a suppression is intentional.",
      "relevant_when": "Deciding whether a script passes validation",
      "why_given": "Errors indicate syntax problems or unsafe constructs that will cause runtime failures; warnings indicate likely bugs."
    },
    {
      "instruction": "Never add a global # shellcheck disable=SCxxxx directive at the top of a file. When suppression is truly needed, add it on the specific line with an explanatory comment.",
      "relevant_when": "Applying ShellCheck suppressions to a script",
      "why_given": "File-level suppressions hide real issues added by future contributors who may not know why the suppression was added."
    },
    {
      "instruction": "Treat #!/bin/sh and #!/usr/bin/env bash shebangs as distinct. A #!/bin/sh script must not use bash-specific syntax (arrays, [[ ]], declare, local without -r). A #!/usr/bin/env bash script must not omit the shebang.",
      "relevant_when": "Validating any shell script's shebang line and syntax",
      "why_given": "Using bash syntax under a sh shebang silently fails on Alpine Linux, minimal containers, and most CI runners."
    },
    {
      "instruction": "Flag any use of eval with a variable as a potential command injection risk. Flag rm -rf calls that operate on unquoted or insufficiently validated variables.",
      "relevant_when": "Running custom security checks during validation",
      "why_given": "These are the two highest-severity security anti-patterns in shell scripts and require explicit human review."
    },
    {
      "instruction": "Never use exit 0 or || true inside a function to suppress errors. Functions should return meaningful exit codes so that callers and set -e can detect failures.",
      "relevant_when": "Reviewing or fixing error handling in shell scripts",
      "why_given": "Suppressing exit codes silently hides failures, making debugging non-deterministic."
    }
  ]
}