diff --git a/src/tests/headers.md b/src/tests/headers.md
index adc5fa6c9..bdbe0a14e 100644
--- a/src/tests/headers.md
+++ b/src/tests/headers.md
@@ -87,6 +87,8 @@ found in [`header.rs`] from the compiletest source.
     * [`revisions`](compiletest.md#revisions) — compile multiple times
     * [`forbid-output`](compiletest.md#incremental-tests) — incremental cfail rejects output pattern
     * [`should-ice`](compiletest.md#incremental-tests) — incremental cfail should ICE
+    * [`known-bug`](ui.md#known-bugs) — indicates that the test is
+      for a known bug that has not yet been fixed
 * [Assembly](compiletest.md#assembly-tests) headers
     * `assembly-output` — the type of assembly output to check
 
diff --git a/src/tests/ui.md b/src/tests/ui.md
index a8e8d3b72..c1c105141 100644
--- a/src/tests/ui.md
+++ b/src/tests/ui.md
@@ -394,6 +394,21 @@ The `ignore-pass` header can be used to ignore the `--pass` CLI flag if the
 test won't work properly with that override.
 
 
+## Known bugs
+
+The `known-bug` header may be used for tests that demonstrate a known bug that
+has not yet been fixed.
+Adding tests for known bugs is helpful for several reasons, including:
+
+1. Maintaining a functional test that can be conveniently reused when the bug is fixed.
+2. Providing a sentinel that will fail if the bug is incidentally fixed.
+   This can alert the developer so they know that the associated issue has
+   been fixed and can possibly be closed.
+
+Do not include [error annotations](#error-annotations) in a test with `known-bug`.
+The test should still include other normal headers and stdout/stderr files.
+
+
 ## Test organization
 
 When deciding where to place a test file, please try to find a subdirectory