3A2DEV review-role
Review an Ansible role and produce a structured severity report. This command never modifies files.
Required Inputs
- role_name or FQCN — The role to review (resolved from discovery if not provided)
Behavior
Step 1 — Discovery
Run discovery per references/discovery.md. Locate the role:
- By name in
roles_pathdirectories - By FQCN in
collections_pathdirectories
Step 2 — Load Role
Read all files in the role directory: tasks/, defaults/, vars/, handlers/, meta/, templates/.
Step 3 — Generate Severity Report
## Role Review: <role_name>
Path: <role_path>
Reviewed: <timestamp>
Tasks found: <count> Handlers: <count>
---
### CRITICAL
[Critical issues]
### WARNING
[Warnings]
### INFO
[Informational notes]
---
Summary: <X> critical, <Y> warnings, <Z> info
Checks to Perform
CRITICAL
| Check | Condition | Message |
|---|---|---|
| Bare module names | Any task uses module without FQCN | [tasks/main.yml:line <N>] Task "<name>" uses bare module name '<mod>' — must use FQCN |
| Missing no_log on secrets | Task has password:, secret:, token:, or references vault_* variables without no_log: true |
[tasks/main.yml:line <N>] Task "<name>" handles secrets without no_log: true |
| Deprecated include syntax | Use of bare include: |
[tasks/main.yml:line <N>] Deprecated 'include:' — use ansible.builtin.include_tasks or ansible.builtin.import_tasks |
| Missing tasks/main.yml | The file does not exist | CRITICAL: tasks/main.yml is missing — role has no entry point |
| Meta/main.yml missing required fields | galaxy_info is absent or missing author/description/min_ansible_version | [meta/main.yml] Missing required galaxy_info field: <field> |
WARNING
| Check | Condition | Message |
|---|---|---|
| Untagged tasks | Any task without tags: |
[tasks/main.yml:line <N>] Task "<name>" has no tags — add component name + action category |
| vars/ used for overridable values | Variable in vars/main.yml that clearly should be in defaults/ (e.g., port, version) | [vars/main.yml] Variable '<var>' looks like an operator-overridable default — consider moving to defaults/main.yml |
| defaults/ used for internal constants | Variable in defaults/main.yml with underscore prefix or clearly internal | [defaults/main.yml] Variable '<var>' looks like an internal constant — consider moving to vars/main.yml |
| Missing directory | Standard dir (files/, templates/, handlers/) absent | Directory '<dir>/' is missing from role structure (not required but recommended) |
| Handler not referenced | Handler defined in handlers/main.yml but no task calls notify: for it |
[handlers/main.yml] Handler '<name>' is defined but never notified by any task |
| Orphaned notify | Task notifies a handler name that doesn't exist in handlers/main.yml | [tasks/main.yml:line <N>] Task notifies '<name>' but no handler with that name/listen exists |
| Shell/command without idempotency | ansible.builtin.shell or ansible.builtin.command without creates:, removes:, or changed_when: |
[tasks/main.yml:line <N>] Task "<name>" uses shell/command without idempotency guard |
| meta/main.yml: min_ansible_version not set | min_ansible_version absent |
[meta/main.yml] min_ansible_version not set — recommend setting to "2.15" |
INFO
| Check | Condition | Message |
|---|---|---|
| No tests/ directory | tests/ absent | No tests/ directory found — consider adding tests/test.yml for smoke testing |
| No validation guidance | role has example content but no clear smoke-test path | Add tests/test.yml or README validation guidance aligned with references/testing.md |
| No README.md | Role has no README | Role is missing a README.md — document variables, dependencies, and usage |
| tasks/main.yml lacks assertions | No ansible.builtin.assert in tasks/main.yml |
Consider adding an assert to validate minimum Ansible version or required variables |
| Templates not validated | ansible.builtin.template task without validate: parameter |
[tasks/main.yml:line <N>] Template task for <dest> could use 'validate:' to verify syntax before deployment |
Constraints
- Never modify files. This command is read-only.
- Do not generate a "fixed" version of any file.
- Do not suggest sed/awk commands.
- Conclude with: "Use
/ansible-designer:update-roleto apply fixes."