1 files changed, 87 insertions, 3 deletions

diff --git a/src/ansiblelint/rules/partial_become.md b/src/ansiblelint/rules/partial_become.md
index 01f9dae..672ef96 100644
--- a/src/ansiblelint/rules/partial_become.md
+++ b/src/ansiblelint/rules/partial_become.md
@@ -5,6 +5,13 @@ This rule checks that privilege escalation is activated when changing users.
 To perform an action as a different user with the `become_user` directive, you
 must set `become: true`.
 
+This rule can produce the following messages:
+
+- `partial-become[play]`: become_user requires become to work as expected, at
+  play level.
+- `partial-become[task]`: become_user requires become to work as expected, at
+  task level.
+
 !!! warning
 
     While Ansible inherits have of `become` and `become_user` from upper levels,
@@ -19,12 +26,13 @@ must set `become: true`.
 ---
 - name: Example playbook
   hosts: localhost
+  become: true # <- Activates privilege escalation.
   tasks:
     - name: Start the httpd service as the apache user
       ansible.builtin.service:
         name: httpd
         state: started
-        become_user: apache # <- Does not change the user because "become: true" is not set.
+      become_user: apache # <- Does not change the user because "become: true" is not set.
 ```
 
 ## Correct Code
@@ -37,6 +45,82 @@ must set `become: true`.
       ansible.builtin.service:
         name: httpd
         state: started
-        become: true # <- Activates privilege escalation.
-        become_user: apache # <- Changes the user with the desired privileges.
+      become: true # <- Activates privilege escalation.
+      become_user: apache # <- Changes the user with the desired privileges.
+
+# Stand alone playbook alternative, applies to all tasks
+
+- name: Example playbook
+  hosts: localhost
+  become: true # <- Activates privilege escalation.
+  become_user: apache # <- Changes the user with the desired privileges.
+  tasks:
+    - name: Start the httpd service as the apache user
+      ansible.builtin.service:
+        name: httpd
+        state: started
+```
+
+## Problematic Code
+
+```yaml
+---
+- name: Example playbook 1
+  hosts: localhost
+  become: true # <- Activates privilege escalation.
+  tasks:
+    - name: Include a task file
+      ansible.builtin.include_tasks: tasks.yml
 ```
+
+```yaml
+---
+- name: Example playbook 2
+  hosts: localhost
+  tasks:
+    - name: Include a task file
+      ansible.builtin.include_tasks: tasks.yml
+```
+
+```yaml
+# tasks.yml
+- name: Start the httpd service as the apache user
+  ansible.builtin.service:
+    name: httpd
+    state: started
+  become_user: apache # <- Does not change the user because "become: true" is not set.
+```
+
+## Correct Code
+
+```yaml
+---
+- name: Example playbook 1
+  hosts: localhost
+  tasks:
+    - name: Include a task file
+      ansible.builtin.include_tasks: tasks.yml
+```
+
+```yaml
+---
+- name: Example playbook 2
+  hosts: localhost
+  tasks:
+    - name: Include a task file
+      ansible.builtin.include_tasks: tasks.yml
+```
+
+```yaml
+# tasks.yml
+- name: Start the httpd service as the apache user
+  ansible.builtin.service:
+    name: httpd
+    state: started
+  become: true # <- Activates privilege escalation.
+  become_user: apache # <- Does not change the user because "become: true" is not set.
+```
+
+!!! note
+
+    This rule can be automatically fixed using [`--fix`](../autofix.md) option.