1 files changed, 58 insertions, 0 deletions
diff --git a/src/ansiblelint/rules/no_free_form.md b/src/ansiblelint/rules/no_free_form.md
new file mode 100644
index 0000000..0ffc0ac
--- /dev/null
+++ b/src/ansiblelint/rules/no_free_form.md
@@ -0,0 +1,58 @@
+# no-free-form
+
+This rule identifies any use of
+[free-form](https://docs.ansible.com/ansible/2.7/user_guide/playbooks_intro.html#action-shorthand)
+module calling syntax and asks for switching to the full syntax.
+
+**Free-form** syntax, also known as **inline** or **shorthand**, can produce
+subtle bugs. It can also prevent editors and IDEs from providing feedback,
+autocomplete and validation for the edited line.
+
+!!! note
+
+    As long you just pass a YAML string that contains a `=` character inside as the
+    parameter to the action module name, we consider this as using free-form syntax.
+    Be sure you pass a dictionary to the module, so the free-form parsing is never
+    triggered.
+
+As `raw` module only accepts free-form, we trigger `no-free-form[raw]` only if
+we detect the presence of `executable=` inside raw calls. We advise the explicit
+use of `args:` for configuring the executable to be run.
+
+This rule can produce messages as:
+
+- `no-free-form` - Free-form syntax is discouraged.
+- `no-free-form[raw-non-string]` - Passing a non-string value to `raw` module is
+  neither documented nor supported.
+
+## Problematic code
+
+```yaml
+---
+- name: Example with discouraged free-form syntax
+  hosts: localhost
+  tasks:
+    - name: Create a placefolder file
+      ansible.builtin.command: chdir=/tmp touch foo # <-- don't use free-form
+    - name: Use raw to echo
+      ansible.builtin.raw: executable=/bin/bash echo foo # <-- don't use executable=
+      changed_when: false
+```
+
+## Correct code
+
+```yaml
+---
+- name: Example that avoids free-form syntax
+  hosts: localhost
+  tasks:
+    - name: Create a placefolder file
+      ansible.builtin.command:
+        cmd: touch foo # <-- ansible will not touch it
+        chdir: /tmp
+    - name: Use raw to echo
+      ansible.builtin.raw: echo foo
+      args:
+        executable: /bin/bash # <-- explicit is better
+      changed_when: false
+```