Update docs with strong prescriptive recommendation on how to handle dynamic form behaviour with custom slot mappings

changelog/11724.doc.md

@@ -0,0 +1 @@
+Update migration guide and form docs with prescriptive recommendation on how to implement dynamic forms with custom slot mappings.

docs/docs/forms.mdx

@@ -300,8 +300,9 @@ If you're using the Rasa SDK we recommend you to extend the provided
 `FormValidationAction`. When using the `FormValidationAction`, three steps are required
 to extract customs slots:
 
-1. Define a method `extract_<slot_name>` for every slot that should be mapped in a
-   custom way.
+1. Define a method `extract_<slot_name>` for every slot that should be mapped in a custom way.
+   Each slot which has been defined in the `domain.yml` file with a custom mapping **must** have its own independent
+   implementation of an `extract_<slot_name>` method.
 2. In your domain file, for your form's `required_slots`, list all required slots, with both predefined and custom mappings.
 
 In addition, you can override the `required_slots` method to add dynamically requested slots: you can read more in the
@@ -346,18 +347,18 @@ first slot specified in `required_slots` which is not filled.
 
 ### Dynamic Form Behavior
 
-By default Rasa will ask for the next empty slot from the slots
+By default, Rasa will ask for the next empty slot from the slots
 listed for your form in the domain file. If you use
 [custom slot mappings](forms.mdx#custom-slot-mappings) and the `FormValidationAction`,
 it will ask for the first empty slot returned by the `required_slots` method. If all
 slots in `required_slots` are filled the form will be deactivated.
 
-If needed, you can update the required slots of your form dynamically.
-This is, for example, useful when you need further details based on how
-a previous slot was filled or you want to change the order in which slots are requested.
+You can update the required slots of your form dynamically.
+This is, for example, useful when you need to fill additional slots based on how
+a previous slot was filled or when you want to change the order in which slots are requested.
 
-If you are using the Rasa SDK, we recommend you to use the `FormValidationAction` and
-override `required_slots` to fit your dynamic behavior. You should implement
+If you are using the Rasa SDK, we strongly recommend that you use the `FormValidationAction` and
+override `required_slots` to fit your dynamic behavior. You must implement
 a method `extract_<slot name>` for every slot which doesn't use a predefined mapping,
 as described in [Custom Slot Mappings](forms.mdx#custom-slot-mappings).
 The example below will ask the user if they want to sit in

docs/docs/migration-guide.mdx

@@ -1443,9 +1443,20 @@ the mappings will be applied on each user turn regardless of whether a form is a
          requested_slot: outdoor_seating
 ```
 
+#### Rasa-SDK Modifications
+
 If you have used `FormValidationAction` to define custom extraction and validation code in which you override the
 `required_slots` method, note that `slots_mapped_in_domain` argument has been replaced by the `domain_slots` argument.
-You will need to make this replacement to continue using your custom code.
+You must make this replacement to continue using your custom code.
+
+If you have been dynamically filling slots not present in the form's `required_slots` defined in the `domain.yml`
+file, note that this behaviour is no longer supported in 3.x. Any dynamic slots with custom mappings, which are set in
+the last user turn, will be filled **only if** they are returned by the `required_slots` method of the custom action
+inheriting from `FormValidationAction`. To maintain the 2.x behaviour, you must now override the `required_slots` method
+of this custom action as per the strong recommendation listed in the [dynamic form documentation](./forms.mdx#dynamic-form-behavior).
+
+To extract custom slots that are not defined in any form's `required_slots`, you should now use a global [custom slot mapping](./domain.mdx#custom-slot-mappings)
+and extend the [ValidationAction class](./action-server/validation-action.mdx#validationaction-class).
 
 :::note
 If you have custom validation actions extending `FormValidationAction` which override `required_slots` method, you should