{
  "instructions": [
    {
      "instruction": "Use Fully Qualified Collection Names (FQCN) for all module references (e.g., `ansible.builtin.copy` not `copy`)",
      "original_snippets": "Use Fully Qualified Collection Names (FQCN) ... ansible.builtin.copy ... Avoid - Short names (deprecated)",
      "relevant_when": "Every task in any generated playbook, role, or task file",
      "why_given": "reminder"
    },
    {
      "instruction": "Use `true`/`false` for booleans, not `yes`/`no`",
      "original_snippets": "Booleans | `true`/`false` | `yes`/`no`",
      "relevant_when": "Any task with boolean parameters (become, enabled, update_cache, etc.)",
      "why_given": "preference"
    },
    {
      "instruction": "Use `ansible.builtin.dnf` (not `ansible.builtin.yum`) for RHEL 8+ / CentOS 8+ package installation",
      "original_snippets": "RHEL packages | `ansible.builtin.dnf` | `ansible.builtin.yum` ... ansible.builtin.yum is deprecated in favor of dnf for modern RHEL systems",
      "relevant_when": "When managing packages on RHEL/CentOS systems",
      "why_given": "new knowledge"
    },
    {
      "instruction": "Apply `no_log: true` to tasks that handle secrets or sensitive data",
      "original_snippets": "Secrets | `no_log: true` | plain logging ... Use no_log for sensitive operations",
      "relevant_when": "Any task setting passwords, tokens, or API keys",
      "why_given": "reminder"
    },
    {
      "instruction": "Set file permissions as quoted octal strings: `'0644'` for configs, `'0600'` for secrets",
      "original_snippets": "File perms | `'0644'` configs, `'0600'` secrets | world-writable",
      "relevant_when": "Tasks using ansible.builtin.file, copy, or template that set file modes",
      "why_given": "preference"
    },
    {
      "instruction": "Never use `shell` or `command` module when a dedicated module exists; use the purpose-built module instead",
      "original_snippets": "NEVER use the `shell` or `command` module when a dedicated module exists ... ansible.builtin.shell: pip install requests instead of using the pip module",
      "relevant_when": "Any task that might be tempted to use shell/command for package install, file ops, service management, etc.",
      "why_given": "new knowledge"
    },
    {
      "instruction": "Every task must have a `name:` field starting with a verb that describes what the task does",
      "original_snippets": "NEVER write tasks without `name:` fields ... Always prefix every task with a descriptive `name:` ... Start with a verb: 'Install nginx', 'Copy configuration file'",
      "relevant_when": "Every generated task",
      "why_given": "reminder"
    },
    {
      "instruction": "Never use `ignore_errors: true` as a general exception handler; use `failed_when` or `block/rescue/always` instead",
      "original_snippets": "NEVER use `ignore_errors: true` as a general exception handler ... Use `failed_when` with specific conditions ... or use `block/rescue/always`",
      "relevant_when": "Any task that might fail and needs error handling",
      "why_given": "new knowledge"
    },
    {
      "instruction": "Never store secrets in `group_vars/` plaintext files; use Ansible Vault or an external secrets manager",
      "original_snippets": "NEVER store secrets in `group_vars/` plaintext files ... Use Ansible Vault (`ansible-vault encrypt_string`) or an external secrets manager",
      "relevant_when": "When generating inventory, group_vars, or host_vars files that might include credentials",
      "why_given": "new knowledge"
    },
    {
      "instruction": "Add a playbook header comment block documenting title, description, requirements, variables, and usage command",
      "original_snippets": "# Playbook: <title>\n# Description: <what it does>\n# Requirements: Ansible 2.10+, <OS>\n# Variables:\n#   - <var_name>: ...\n# Usage: ansible-playbook -i inventory/<env> <playbook>.yml",
      "relevant_when": "When generating a complete playbook file",
      "why_given": "preference"
    },
    {
      "instruction": "Prefix all role variables with the role name (e.g., `nginx_port`, `nginx_worker_processes`)",
      "original_snippets": "Prefix all role variables with the role name (e.g., `nginx_port`, `nginx_worker_processes`)",
      "relevant_when": "When generating Ansible roles with variables",
      "why_given": "preference"
    },
    {
      "instruction": "Use `include_vars` for OS-specific variables in roles (e.g., vars/Debian.yml, vars/RedHat.yml)",
      "original_snippets": "Use `include_vars` for OS-specific variables",
      "relevant_when": "When generating roles that support multiple operating systems",
      "why_given": "preference"
    },
    {
      "instruction": "Use `state: present/absent` and dedicated modules for idempotent operations; when `command`/`shell` is unavoidable use `creates`, `removes`, or `changed_when`",
      "original_snippets": "All tasks should be idempotent ... Use `state: present/absent` ... When using `command`/`shell`, use `creates`, `removes`, or `changed_when`",
      "relevant_when": "Every task, especially those that might be run multiple times",
      "why_given": "reminder"
    },
    {
      "instruction": "Restart services via handlers triggered by `notify:`, not via direct restart tasks",
      "original_snippets": "Not using handlers - Restart services via handlers, not direct tasks ... notify: Restart nginx",
      "relevant_when": "When a task modifies a configuration file or package that requires a service restart",
      "why_given": "reminder"
    },
    {
      "instruction": "Set `gather_facts: false` globally in `ansible.cfg` and enable per-play only when facts are actually needed",
      "original_snippets": "NEVER use `gather_facts: true` by default for large inventories ... Set `gather_facts: false` globally in `ansible.cfg` and enable it per-play only when facts are actually needed",
      "relevant_when": "When generating playbooks or ansible.cfg for large inventories or utility plays",
      "why_given": "new knowledge"
    },
    {
      "instruction": "Add tags to tasks using appropriate categories (`install`, `configure`, `update`, `backup`)",
      "original_snippets": "tags:\n  - packages\n  - nginx\n  - install",
      "relevant_when": "When generating task files or playbooks with multiple operational phases",
      "why_given": "preference"
    },
    {
      "instruction": "Use `block/rescue/always` for structured error handling with recovery logic instead of `ignore_errors`",
      "original_snippets": "use `block/rescue/always` for structured error handling with recovery logic",
      "relevant_when": "When a sequence of tasks needs rollback capability or guaranteed cleanup",
      "why_given": "new knowledge"
    },
    {
      "instruction": "When using non-builtin collections, include installation instructions in comments (`ansible-galaxy collection install <name>:<version>`)",
      "original_snippets": "# Requirements:\n#   - ansible-galaxy collection install kubernetes.core:2.4.0",
      "relevant_when": "When generating playbooks that use community or cloud provider collections",
      "why_given": "preference"
    },
    {
      "instruction": "Use `async` and `ansible.builtin.async_status` for long-running tasks instead of blocking",
      "original_snippets": "async: 3600\n  poll: 0\n  register: migration\n- name: Check migration status\n  ansible.builtin.async_status:\n    jid: '{{ migration.ansible_job_id }}'",
      "relevant_when": "When generating tasks for operations that may take minutes (database migrations, large downloads, builds)",
      "why_given": "new knowledge"
    },
    {
      "instruction": "Generate a complete role structure including tasks/main.yml, handlers/main.yml, defaults/main.yml, vars/main.yml, meta/main.yml, and README.md",
      "original_snippets": "Copy and customize the full role structure from `assets/templates/role/`:\n  - `tasks/main.yml`, `handlers/main.yml`, `templates/`, `files/`\n  - `vars/main.yml`, `vars/Debian.yml`, `vars/RedHat.yml`\n  - `defaults/main.yml`, `meta/main.yml`, `meta/argument_specs.yml` (Ansible 2.11+), `README.md`",
      "relevant_when": "When generating a full Ansible role",
      "why_given": "preference"
    }
  ]
}