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.
Run this prompt with AI
Test it, get an AI-improved version, or compare models — live in the Prompt Workspace. No copy-paste.
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.
Related prompts
-
Ansible Monolith to Roles Refactor Prompt
Break a long monolithic playbook into clean, reusable roles with proper defaults/vars/handlers split and a behavior-preserving migration plan.
-
Design an Ansible Dynamic Inventory Prompt
Replace a brittle static inventory with a dynamic inventory plugin (AWS/GCP/Azure or custom script) that auto-groups hosts by tags and keeps group_vars wiring intact.
-
Ansible Dynamic Inventory Plugin Authoring Prompt
Draft a custom dynamic inventory plugin that builds hosts, groups, and vars from an external source, with caching and a verifiable graph output.
-
Ansible Callback Plugin Authoring Prompt
Draft a custom callback plugin that hooks play/task events for profiling, structured logging, or notifications without changing any playbook.
More Ansible prompts & error guides
Browse every Ansible prompt and troubleshooting guide in one place.
Reading prompts? Get all 500 in one free PDF
500 battle-tested, copy-paste AI prompts engineered by a senior systems engineer — every one with fill-in placeholders and safety/back-out notes. Drop your email and it's yours.
- 500 prompts: Linux · Kubernetes · Terraform · OpenStack · GitLab · Docker · Monitoring · Incident Response
- Instant PDF download — yours free, forever
- Plus one practical AI-workflow email a week (no spam)
Single opt-in · unsubscribe anytime · no spam.