ansible-workspace-dnd/docs/conventions.md

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.

Ansible House Style (Normative)

• 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.
• Do not strengthen the specification. Implement the requested invariants without inventing additional guarantees for integrity, provenance, drift recovery, corruption detection, rollback, or similar behavior.
• Prefer convergence over state inspection. Declare what should be true and let the relevant module reconcile it.
• Trust Ansible's abstraction boundary. A module that manages state owns the checks necessary to manage that state. Inspect it beforehand only when the observed state is independently required.
• Complexity requires a requirement. Every additional task, conditional, registered variable, or state probe must correspond to behavior the role is required to provide.
• Persisted role-private state is a design smell. Fingerprints, checksum databases, stamps, manifests, and similar bookkeeping require specific justification.
• Assume convergence first. Before adding machinery for an edge case, determine whether rerunning the ordinary desired-state operations already repairs it.
• 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.