Workspace Conventions

Working Conventions

Confirm the target repository before editing; never treat this directory as a monorepo.
Inspect the relevant upstream application before designing or changing its Ansible role.
Keep standalone application roles independently usable. Cross-application policy belongs in ansible-role-dnd-pipeline and is exposed to consumers as rakestraw.dnd.pipeline.
Prefer codebase-memory graph tools for code discovery. Use text/file search for documentation, configuration, literals, or when the graph is insufficient.
Preserve unrelated and pre-existing working-tree changes in every repository.
Never place credentials or secret values in plans, examples, inventory, or tests.
Validate changes in the repository that owns them and report the commands run.
Do not duplicate an application contract in workspace documentation when a link and a concise deployment consequence are sufficient.

Always use the smallest clear sequence of declarative tasks that reaches the required end state.
Prefer ansible.builtin modules where they directly fit the task. community.general is an approved, stable dependency and its modules may be selected freely when appropriate; declare and pin the collection wherever a role or collection depends on it.
Trust the documented contract of each Ansible module, including its idempotence and change detection.
Gather state only when the result controls necessary behavior that the responsible module cannot determine. Fingerprints, checksums, sidecar state, manual drift detection, and speculative recovery paths require an explicit acceptance criterion and rationale. Do not precede a declarative module with a probe or recreate its internal logic unless a concrete requirement cannot be expressed by the module itself.
Consider whether a conditional task or a notified handler best expresses the dependency. A when condition keeps triggers visible at the action site but grows with their number. Notifications keep the action independent of the number of notifiers, but distribute the control flow and defer execution until the next handler flush. An explicit ansible.builtin.meta: flush_handlers affects all pending handlers in the play.
Treat rakestraw-ansible as a style reference for direct tasks, shallow control flow, and concise variable use, while retaining current practices such as fully qualified collection names.