diff --git a/Library/Homebrew/cli/parser.rb b/Library/Homebrew/cli/parser.rb
index 35f7fd7124030..d1e731dbf1610 100644
--- a/Library/Homebrew/cli/parser.rb
+++ b/Library/Homebrew/cli/parser.rb
@@ -194,7 +194,7 @@ def comma_array(name, description: nil)
         end
       end
 
-      def flag(*names, description: nil, required_for: nil, depends_on: nil)
+      def flag(*names, description: nil, replacement: nil, required_for: nil, depends_on: nil)
         required = if names.any? { |name| name.end_with? "=" }
           OptionParser::REQUIRED_ARGUMENT
         else
@@ -202,8 +202,13 @@ def flag(*names, description: nil, required_for: nil, depends_on: nil)
         end
         names.map! { |name| name.chomp "=" }
         description = option_to_description(*names) if description.nil?
-        process_option(*names, description)
+        if replacement.nil?
+          process_option(*names, description)
+        else
+          description += " (disabled#{"; replaced by #{replacement}" if replacement.present?})"
+        end
         @parser.on(*names, *wrap_option_desc(description), required) do |option_value|
+          odisabled "the `#{names.first}` flag", replacement unless replacement.nil?
           names.each do |name|
             @args[option_to_name(name)] = option_value
           end
diff --git a/Library/Homebrew/dev-cmd/pr-pull.rb b/Library/Homebrew/dev-cmd/pr-pull.rb
index daa2bcaf2faa4..de6f2abef6da8 100644
--- a/Library/Homebrew/dev-cmd/pr-pull.rb
+++ b/Library/Homebrew/dev-cmd/pr-pull.rb
@@ -51,7 +51,9 @@ def pr_pull_args
              description: "Message to include when autosquashing revision bumps, deletions, and rebuilds."
       flag   "--workflow=",
              description: "Retrieve artifacts from the specified workflow (default: `tests.yml`). "\
-                          "Legacy: use --workflows instead"
+                          "*Legacy:* use `--workflows` instead."
+      # TODO: enable for next major/minor release
+      #      replacement: "`--workflows`"
       flag   "--artifact=",
              description: "Download artifacts with the specified name (default: `bottles`)."
       flag   "--bintray-org=",
diff --git a/docs/Manpage.md b/docs/Manpage.md
index e5efc8543cb72..badc2bb98ffee 100644
--- a/docs/Manpage.md
+++ b/docs/Manpage.md
@@ -1151,7 +1151,7 @@ Requires write access to the repository.
 * `--message`:
   Message to include when autosquashing revision bumps, deletions, and rebuilds.
 * `--workflow`:
-  Retrieve artifacts from the specified workflow (default: `tests.yml`). Legacy: use --workflows instead
+  Retrieve artifacts from the specified workflow (default: `tests.yml`). *Legacy:* use `--workflows` instead.
 * `--artifact`:
   Download artifacts with the specified name (default: `bottles`).
 * `--bintray-org`:
diff --git a/manpages/brew.1 b/manpages/brew.1
index 006860ffd51dc..27997ee3005c2 100644
--- a/manpages/brew.1
+++ b/manpages/brew.1
@@ -1605,7 +1605,7 @@ Message to include when autosquashing revision bumps, deletions, and rebuilds\.
 .
 .TP
 \fB\-\-workflow\fR
-Retrieve artifacts from the specified workflow (default: \fBtests\.yml\fR)\. Legacy: use \-\-workflows instead
+Retrieve artifacts from the specified workflow (default: \fBtests\.yml\fR)\. \fILegacy:\fR use \fB\-\-workflows\fR instead\.
 .
 .TP
 \fB\-\-artifact\fR