diff --git a/oslo_policy/generator.py b/oslo_policy/generator.py
index 485aba61..38c9b5b7 100644
--- a/oslo_policy/generator.py
+++ b/oslo_policy/generator.py
@@ -149,12 +149,13 @@ def _format_rule_default_yaml(default, include_help=True):
         deprecated_text = (
             'DEPRECATED\n"%(old_name)s":"%(old_check_str)s" has been '
             'deprecated since %(since)s in favor of '
-            '"%(name)s":"%(check_str)s".'
+            '"%(name)s":"%(check_str)s".\n%(reason)s'
         ) % {'old_name': default.deprecated_rule.name,
              'old_check_str': default.deprecated_rule.check_str,
              'since': default.deprecated_since,
              'name': default.name,
-             'check_str': default.check_str}
+             'check_str': default.check_str,
+             'reason': default.deprecated_reason}
 
         text = (
             '%(text)s%(deprecated_text)s\n"%(old_name)s": "rule:%(name)s"\n'
diff --git a/oslo_policy/tests/test_generator.py b/oslo_policy/tests/test_generator.py
index afcf8e6a..e0aac6d3 100644
--- a/oslo_policy/tests/test_generator.py
+++ b/oslo_policy/tests/test_generator.py
@@ -191,6 +191,7 @@ class GenerateSampleYAMLTestCase(base.PolicyBaseTestCase):
 # DEPRECATED
 # "foo:post_bar":"role:fizz" has been deprecated since N in favor of
 # "foo:create_bar":"role:fizz".
+# foo:post_bar is being removed in favor of foo:create_bar
 "foo:post_bar": "rule:foo:create_bar"
 '''
         stdout = self._capture_stdout()