review-collection
Review an Ansible collection and produce a structured severity report. This command never modifies files.
Required Inputs
- collection identification —
namespace.nameor path to collection root (resolved from discovery if not provided)
Behavior
Step 1 — Discovery
Run discovery per references/discovery.md. Locate the collection:
- By
namespace.nameincollections_pathdirectories - By path if provided directly
Step 2 — Load Collection
Read galaxy.yml, meta/runtime.yml, README.md, CHANGELOG.md, LICENSE. Scan plugins/, roles/, playbooks/, tests/ directories.
Step 3 — Generate Severity Report
## Collection Review: <namespace>.<name>
Path: <collection_path>
Version: <version>
Reviewed: <timestamp>
---
### CRITICAL
[Critical issues]
### WARNING
[Warnings]
### INFO
[Informational notes]
---
Summary: <X> critical, <Y> warnings, <Z> infoChecks to Perform
CRITICAL
| Check | Condition | Message |
|---|---|---|
| galaxy.yml missing | File does not exist | CRITICAL: galaxy.yml is missing — collection is not valid without it |
| galaxy.yml: namespace missing | namespace field absent or empty | [galaxy.yml] Required field 'namespace' is missing |
| galaxy.yml: name missing | name field absent or empty | [galaxy.yml] Required field 'name' is missing |
| galaxy.yml: version missing | version field absent or empty | [galaxy.yml] Required field 'version' is missing |
| galaxy.yml: invalid version | Version is not semver (MAJOR.MINOR.PATCH) | [galaxy.yml] Version '<ver>' is not valid semantic versioning (expected MAJOR.MINOR.PATCH) |
| galaxy.yml: authors missing | authors list is empty or absent | [galaxy.yml] Required field 'authors' is missing or empty |
| Module syntax error | A plugin file has a Python syntax error | [plugins/modules/<file>] Python syntax error: <error> |
WARNING
| Check | Condition | Message |
|---|---|---|
| README.md missing | File does not exist | README.md is missing — add a collection overview with installation and usage instructions |
| CHANGELOG.md missing | File does not exist | CHANGELOG.md is missing — document version history for users |
| LICENSE missing | File does not exist | LICENSE file is missing — add a license (Apache 2.0 recommended) |
| meta/runtime.yml missing | File does not exist | meta/runtime.yml is missing — add 'requires_ansible' constraint |
| meta/runtime.yml: no requires_ansible | requires_ansible absent | [meta/runtime.yml] 'requires_ansible' not set — recommend adding ">=2.15.0" |
| galaxy.yml: no dependencies listed | Dependencies field absent or empty when community collections are likely needed | [galaxy.yml] No dependencies declared — if this collection uses community.general or similar, add them |
| galaxy.yml: no tags | tags field absent or empty | [galaxy.yml] No tags set — add relevant tags to improve Galaxy discoverability |
| Role quality issues | Any role fails review-role checks | For each failing role, add a WARNING with the role name and check that failed |
| Module missing DOCUMENTATION | A plugin module lacks the DOCUMENTATION constant | [plugins/modules/<file>] Module is missing DOCUMENTATION block — required for ansible-doc |
| Module missing EXAMPLES | A plugin module lacks the EXAMPLES constant | [plugins/modules/<file>] Module is missing EXAMPLES block |
| Module missing RETURN | A plugin module lacks the RETURN constant | [plugins/modules/<file>] Module is missing RETURN block |
| Missing test guidance for plugins | Collection contains plugins but no ansible-test or usage guidance | [tests/] Collection contains plugins but has no clear validation path aligned with references/testing.md |
INFO
| Check | Condition | Message |
|---|---|---|
| No roles defined | roles/ directory is empty | No roles found in roles/ — use /ansible-designer:new-role to add a role |
| No tests defined | tests/ directory is empty | No tests found — consider adding integration tests for CI validation |
| No playbooks | playbooks/ directory is empty | No example playbooks found — consider adding a usage example in playbooks/ |
| galaxy.yml: no repository | repository field absent | [galaxy.yml] No repository URL set |
| galaxy.yml: description too long | description > 255 characters | [galaxy.yml] Description is <N> characters — Galaxy recommends under 255 |
Role Quality Checks
For each role found in roles/:
- Run the review-role checks (FQCN, tags, no_log, meta/main.yml validity, handler correctness)
- Prefix each finding with
[roles/<role_name>] - Include role issues in the appropriate severity sections
Constraints
- Never modify files. This command is read-only.
- Do not generate fixed versions of any file.
- Conclude with: "Use
/ansible-designer:update-collectionto apply fixes."