Add docs clarifying behavior of retry files (#65153)

docs/docsite/rst/user_guide/intro_patterns.rst

@@ -153,6 +153,10 @@ Finally, you can use ``--limit`` to read the list of hosts from a file by prefix
 
     ansible-playbook site.yml --limit @retry_hosts.txt
 
+If :ref:`RETRY_FILES_ENABLED` is set to ``True``, a ``.retry`` file will be created after the ``ansible-playbook`` run containing a list of failed hosts from all plays. This file is overwritten each time ``ansible-playook`` finishes running.
+
+    ansible-playbook site.yml --limit @site.retry
+
 To apply your knowledge of patterns with Ansible commands and playbooks, read :ref:`intro_adhoc` and :ref:`playbooks_intro`.
 
 .. seealso::

lib/ansible/config/base.yml

@@ -1754,7 +1754,9 @@ RETRY_FILES_ENABLED:
 RETRY_FILES_SAVE_PATH:
   name: Retry files path
   default: ~
-  description: This sets the path in which Ansible will save .retry files when a playbook fails and retry files are enabled.
+  description:
+    - This sets the path in which Ansible will save .retry files when a playbook fails and retry files are enabled.
+    - This file will be overwritten after each run with the list of failed hosts from all plays.
   env: [{name: ANSIBLE_RETRY_FILES_SAVE_PATH}]
   ini:
   - {key: retry_files_save_path, section: defaults}