diff --git a/.github/workflows/__diagnostics-without-db.yml b/.github/workflows/__diagnostics-without-db.yml
index 2122225a2..28472c95a 100644
--- a/.github/workflows/__diagnostics-without-db.yml
+++ b/.github/workflows/__diagnostics-without-db.yml
@@ -45,9 +45,12 @@ jobs:
     runs-on: ${{ matrix.os }}
     steps:
       # We deliberately need to make this step fail before the database is initialised, but after
-      # some diagnostic has been produced. The simplest way to do that right now is to force the
-      # use of a nightly release and then fail because we are attempting to analyse Swift on
-      # a non-macOS runner.
+      # some diagnostic has been produced. The simplest way to do that right now is to:
+      #
+      # - Produce a diagnostic before the db is initialised by forcing the use of a nightly release
+      #   with the `CODEQL_ACTION_FORCE_NIGHTLY` feature flag.
+      # - Cause `init` to abort because we are attempting to analyse Swift on a non-macOS runner.
+      #
       - name: Check out repository
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
       - name: Install Node.js
diff --git a/pr-checks/checks/diagnostics-without-db.yml b/pr-checks/checks/diagnostics-without-db.yml
index d15878cfc..0d43f1c62 100644
--- a/pr-checks/checks/diagnostics-without-db.yml
+++ b/pr-checks/checks/diagnostics-without-db.yml
@@ -1,7 +1,7 @@
 name: "Diagnostic export without database"
 description: "Tests that temporary diagnostics are correctly included in the failed SARIF."
 versions:
-  # Overridden by the FF below.
+  # Overridden by the FF in the `init` step below.
   - linked
 installNode: true
 
@@ -15,9 +15,12 @@ env:
 
 steps:
   # We deliberately need to make this step fail before the database is initialised, but after
-  # some diagnostic has been produced. The simplest way to do that right now is to force the
-  # use of a nightly release and then fail because we are attempting to analyse Swift on
-  # a non-macOS runner.
+  # some diagnostic has been produced. The simplest way to do that right now is to:
+  #
+  # - Produce a diagnostic before the db is initialised by forcing the use of a nightly release
+  #   with the `CODEQL_ACTION_FORCE_NIGHTLY` feature flag.
+  # - Cause `init` to abort because we are attempting to analyse Swift on a non-macOS runner.
+  #
   - name: Initialise failing analysis
     id: init
     uses: ./../action/init