Ansible Undocumented Inventory and Playbook Documentation Prompt
Reverse-engineer an undocumented inventory and playbook set into a clear README, variable reference, and a Mermaid run-flow diagram.
- Target user
- Engineers who inherited an Ansible repo with no docs and need to understand and hand it off
- Difficulty
- Beginner
- Tools
- Claude, ChatGPT, Cursor
The prompt
You are a senior automation engineer who is excellent at reverse-engineering an inherited, undocumented Ansible repo and writing the README the original author never did. You read inventory, group_vars, roles, and playbooks and reconstruct what the automation actually does and how to run it safely. I will paste the inventory, variable files, and playbooks. Produce documentation that lets a new engineer understand and operate this repo without guessing. Steps: 1. **Inventory map**: list groups and host patterns, the group hierarchy (`children`), and which hosts land in which groups. Note dynamic vs static inventory. 2. **Variable reference**: build a table of the meaningful variables — name, where it's defined (`group_vars`/`host_vars`/`defaults`/`vars`), default/example value, and what it controls. Mark vault-encrypted vars as secret without printing their values. 3. **Playbook catalog**: for each playbook, document its purpose, which hosts/groups it targets, the roles it pulls in, important tags, and whether it uses `become`. 4. **Run-flow diagram**: produce a Mermaid diagram showing playbook -> targeted groups -> roles -> key tasks/handlers so the execution flow is visible at a glance. 5. **How to run safely**: the exact commands to run each playbook, recommended `--check --diff` and `--limit` usage, required collections/`requirements.yml`, and any prerequisites (vault password, SSH keys, become). 6. **Open questions / risks**: list anything ambiguous, undocumented assumptions, or risky tasks a new operator should confirm before running. Fill in: - Inventory file(s): [PASTE] - group_vars / host_vars / defaults: [PASTE OR LIST] - Playbooks and roles: [PASTE OR LIST PATHS + CONTENT] - Anything you already know about the repo: [DESCRIBE OR "nothing"] Output format: a README in markdown with sections (Overview, Inventory, Variables table, Playbook catalog, Run-flow Mermaid diagram, How to run safely, Open questions). Never print decrypted vault values — reference secret vars by name only. This is documentation, not execution. Do not run any playbook. Recommend a --check --diff dry run on a single host as the safe first step for anyone operating this repo, and surface risky tasks in the Open questions section for human review.
Why this prompt works
Inherited Ansible repos are usually undocumented, and the cost lands on whoever runs them next and guesses wrong about which hosts a playbook hits or what a variable does. The prompt rebuilds the missing mental model from the artifacts that don’t lie — inventory hierarchy, variable definitions and their precedence locations, and per-playbook targeting — so a new operator can understand the system without spelunking through every file.
The Mermaid run-flow diagram is the payoff feature. Turning playbook -> groups -> roles -> handlers into a single picture makes execution flow obvious in a way that a wall of YAML never does, which is exactly what speeds up onboarding and review.
The two safety habits keep the documentation trustworthy and committable: secret variables are referenced by name and never decrypted, and inferred behavior is labeled as assumed and confirmed with a --check --diff rather than trusted blindly. The output is a README you can drop into the repo, with an Open Questions section that honestly flags what still needs a human to verify.