{
  "instructions": [
    {
      "instruction": "Run bash scripts/setup_tools.sh for diagnostics on first-time validation",
      "original_snippets": "0. Tool Prerequisites Check (RECOMMENDED for first-time validation)\n   └─> Run bash scripts/setup_tools.sh for diagnostics",
      "relevant_when": "First-time validation or when tool availability is uncertain",
      "why_given": "new knowledge"
    },
    {
      "instruction": "Run yamllint before ansible-playbook --syntax-check; fix YAML errors first",
      "original_snippets": "Run `yamllint` then `ansible-playbook --syntax-check`. Fix YAML errors first, then Ansible-specific issues.",
      "relevant_when": "Validating any Ansible playbook or role",
      "why_given": "preference"
    },
    {
      "instruction": "Run ansible-lint to enforce best practices; use --fix for auto-fixable issues and review before applying",
      "original_snippets": "Run `ansible-lint` to enforce best practices. Use `--fix` for auto-fixable issues; review before applying.",
      "relevant_when": "Validating Ansible playbooks or roles",
      "why_given": "preference"
    },
    {
      "instruction": "Check for deprecated modules using references/module_alternatives.md",
      "original_snippets": "├─> Check for deprecated modules (references/module_alternatives.md)",
      "relevant_when": "When ansible-lint or manual review finds deprecated module usage",
      "why_given": "new knowledge"
    },
    {
      "instruction": "Detect non-FQCN module usage by running bash scripts/check_fqcn.sh",
      "original_snippets": "├─> Detect non-FQCN usage: bash scripts/check_fqcn.sh",
      "relevant_when": "Validating any Ansible playbook or role",
      "why_given": "new knowledge"
    },
    {
      "instruction": "Run ansible-playbook --check --diff (not just --check); always use both flags together for dry-run testing",
      "original_snippets": "NEVER run `--check` mode without `--diff`\n...GOOD: `ansible-playbook --check --diff site.yml`",
      "relevant_when": "Performing dry-run testing of Ansible playbooks",
      "why_given": "new knowledge"
    },
    {
      "instruction": "When molecule/ directory is detected in a role, run bash scripts/test_role.sh <role-path> automatically",
      "original_snippets": "├─> If present, run bash scripts/test_role.sh <role-path> automatically",
      "relevant_when": "Validating Ansible roles that have a molecule/ directory",
      "why_given": "new knowledge"
    },
    {
      "instruction": "If molecule fails due to environment (Docker, versions), document the blocker but do not fail overall validation; if it fails due to role code, provide debugging steps",
      "original_snippets": "If molecule fails due to environment (Docker, versions), document the blocker but don't fail overall validation. If molecule fails due to role code, provide detailed debugging steps.",
      "relevant_when": "Running molecule tests in environments that may not have Docker",
      "why_given": "preference"
    },
    {
      "instruction": "Run bash scripts/extract_ansible_info_wrapper.sh <path> to extract module/collection information",
      "original_snippets": "├─> Run bash scripts/extract_ansible_info_wrapper.sh <path> to extract info",
      "relevant_when": "When playbooks use custom modules or collections",
      "why_given": "new knowledge"
    },
    {
      "instruction": "For public collections, use Context7 MCP (mcp__context7__resolve-library-id then get-library-docs) for documentation lookup",
      "original_snippets": "**For public collections** (community.general, ansible.posix, cisco.ios, etc.):\n1. `mcp__context7__resolve-library-id` with collection name\n2. `mcp__context7__get-library-docs` for specific module",
      "relevant_when": "When playbooks use public Ansible Galaxy collections",
      "why_given": "new knowledge"
    },
    {
      "instruction": "For custom/private collections, use WebSearch with format '[collection-namespace].[module-name] ansible version [version] documentation'",
      "original_snippets": "**For custom/private collections** — use WebSearch:\n\"[collection-namespace].[module-name] ansible version [version] documentation\"",
      "relevant_when": "When playbooks use private or custom Ansible collections",
      "why_given": "new knowledge"
    },
    {
      "instruction": "Run bash scripts/validate_playbook_security.sh or validate_role_security.sh for Checkov security scanning",
      "original_snippets": "├─> Run bash scripts/validate_playbook_security.sh or validate_role_security.sh (Checkov)",
      "relevant_when": "Any Ansible validation task",
      "why_given": "new knowledge"
    },
    {
      "instruction": "Run bash scripts/scan_secrets.sh to detect hardcoded credentials",
      "original_snippets": "└─> Run bash scripts/scan_secrets.sh (detects hardcoded credentials)",
      "relevant_when": "Any Ansible validation task",
      "why_given": "new knowledge"
    },
    {
      "instruction": "Read references/common_errors.md when errors are detected",
      "original_snippets": "├─> Read references/common_errors.md when errors detected",
      "relevant_when": "When validation tools produce errors",
      "why_given": "preference"
    },
    {
      "instruction": "Read references/best_practices.md when warnings are detected",
      "original_snippets": "├─> Read references/best_practices.md when warnings detected",
      "relevant_when": "When ansible-lint or other tools produce warnings",
      "why_given": "preference"
    },
    {
      "instruction": "Read references/module_alternatives.md for deprecated or non-FQCN modules",
      "original_snippets": "├─> Read references/module_alternatives.md for deprecated/non-FQCN modules",
      "relevant_when": "When deprecated modules or non-FQCN usage is detected",
      "why_given": "preference"
    },
    {
      "instruction": "Read references/security_checklist.md when security issues are found",
      "original_snippets": "└─> Read references/security_checklist.md when security issues found",
      "relevant_when": "When security scanning finds vulnerabilities",
      "why_given": "preference"
    },
    {
      "instruction": "Never skip ansible-lint because the playbook 'works'; run in CI before every merge and treat violations as build failures",
      "original_snippets": "NEVER skip `ansible-lint` because the playbook \"works\"\n...GOOD: Run `ansible-lint` in CI before every merge and treat any rule violation as a build failure.",
      "relevant_when": "Any Ansible validation task",
      "why_given": "new knowledge"
    },
    {
      "instruction": "Never use molecule test as a substitute for ansible-lint; run ansible-lint first (fast), then molecule (slower); both gates required",
      "original_snippets": "NEVER use `molecule test` as a substitute for `ansible-lint`\n...GOOD: Run `ansible-lint` first (fast, catches obvious errors), then Molecule (slower, catches runtime and idempotency errors) — both gates are required.",
      "relevant_when": "Validating Ansible roles with molecule tests",
      "why_given": "new knowledge"
    },
    {
      "instruction": "Never ignore no-changed-when warnings; add changed_when: false for read-only commands or explicit changed_when condition for state-changing ones",
      "original_snippets": "NEVER ignore `no-changed-when` lint warnings\n...GOOD: Add `changed_when: false` for genuinely read-only commands, or add an explicit `changed_when` condition",
      "relevant_when": "Playbooks with command or shell tasks",
      "why_given": "new knowledge"
    },
    {
      "instruction": "Never disable validate_certs in get_url or other network tasks",
      "original_snippets": "# BAD\n- get_url:\n    url: https://example.com/file.tar.gz\n    dest: /tmp/file.tar.gz\n    validate_certs: false",
      "relevant_when": "Playbooks using get_url, uri, or other network modules",
      "why_given": "reminder"
    },
    {
      "instruction": "Use Ansible Vault or environment variables for secrets; never hardcode credentials",
      "original_snippets": "**Secrets:** Use Ansible Vault / environment variables; never hardcode credentials",
      "relevant_when": "Playbooks handling passwords, API keys, or sensitive data",
      "why_given": "reminder"
    },
    {
      "instruction": "Always set mode: on file/template tasks",
      "original_snippets": "**File permissions:** Always set `mode:` on file/template tasks; encrypt sensitive files",
      "relevant_when": "Playbooks with file, template, or copy tasks",
      "why_given": "reminder"
    },
    {
      "instruction": "Validation order: YAML syntax → Ansible syntax → Lint → Security scan → Secrets scan → Check mode → Molecule tests",
      "original_snippets": "Validation order: YAML syntax → Ansible syntax → Lint → Security scan → Secrets scan → Check mode → Molecule tests",
      "relevant_when": "Full validation pass on any Ansible playbook or role",
      "why_given": "preference"
    },
    {
      "instruction": "Pin collection versions in requirements.yml; test before upgrading",
      "original_snippets": "Pin collection versions in `requirements.yml`; test before upgrading",
      "relevant_when": "Playbooks or roles using Galaxy collections",
      "why_given": "reminder"
    }
  ]
}