update-role

Update one or more files in an existing Ansible role. Always shows a diff and waits for confirmation before writing.

Required Inputs

1. role_name or FQCN — The role to update (resolved from discovery)
2. change_description — What to change (e.g., "add Windows support", "fix bare module names in tasks/main.yml", "add SELinux task to RedHat.yml")

Behavior

Step 1 — Discovery

Locate the role via discovery (references/discovery.md).

Step 2 — Load Target Files

Read only the files relevant to the requested change. If the change affects multiple files (e.g., "add multi-OS support"), read all affected files.

Step 2a — Secret Scan (before any output)

Before displaying any content or diff — especially for defaults/main.yml, vars/*.yml, and group_vars/ files — scan every loaded file for credential-like values:

• Match lines or YAML values where the key contains password, secret, token, api_key, private_key, pass, or credential
• Skip lines where the value is already a vault reference ({{ vault_* }}), a task option (no_log, register, when), empty, or None
• For any remaining matches, redact the value in all output: db_password: "***REDACTED***"
• Emit a warning at the top of each affected file's diff block:

  ⚠ Warning: N line(s) with credential-like values were redacted from this display.
    Review the file directly before applying changes.

• Never output actual credential values in diffs, summaries, or confirmations.

Step 3 — Apply Change

Apply the requested change to the relevant files:

• Preserve existing structure, indentation style, and comments
• All modules use FQCN
• All new tasks have tags (role_name + action category)
• no_log: true on any new task handling secrets per references/security_vault.md
• Use templates from references/role.md for any new blocks
• Keep tests and smoke-playbook updates aligned with references/testing.md

Step 4 — Show Unified Diff (per file)

For each modified file, show the diff:

--- roles/nginx/tasks/main.yml (original)
+++ roles/nginx/tasks/main.yml (proposed)
@@ -12,6 +12,12 @@
   tags:
     - nginx
     - configure
+
+- name: Open firewall port for nginx
+  ansible.posix.firewalld:
+    port: "{{ nginx_port }}/tcp"
+    permanent: true
+    state: enabled
+    immediate: true
+  tags:
+    - nginx
+    - security

Then ask: "Apply these changes? (yes/no)"

Step 5 — Write on Confirmation

• If yes: write all modified files.
• If no: ask what to change and loop back to Step 3.

Step 6 — Final Output

Show file tree of the updated role:

find "roles/<role_name>" -type f | sort

Suggest next step:

Next step: Run `ansible-lint roles/<role_name>/` to validate
           or use /ansible-designer:review-role to re-check for remaining issues.

Change Types Supported

Safety Rules

• Never remove tasks unless explicitly requested.
• Never change the role name or its meta role_name field without explicit request.
• Preserve all existing comments.
• If adding OS support to an existing role that already has tasks in main.yml: do NOT remove those tasks. Wrap existing platform-independent tasks to remain in main.yml and move platform-specific tasks to the OS files.
• If the change would break backward compatibility (e.g., removing a defaults variable), warn before asking for confirmation.