feat(ui): name the operation in completing-read prompts

A picker prompt is the last thing shown before a command commits, so a bare noun leaves a mis-keyed command ambiguous. Hitting C-f8 (project agenda) instead of C-f9 (AI-vterm picker) gave the same "Project:" prompt with no signal which one was about to run.

Reworded 17 prompts across 8 modules so each names the operation rather than just the thing being chosen: "Project:" becomes "Show agenda for project:", "F6:" becomes "Run tests:", the dwim-shell sub-prompts gain their context (checksum algorithm, PDF compression quality, text-to-speech voice, run dwim-shell command), the two contact pickers split into "Find contact:" and "Insert contact email:", and the dirvish ediff, org finalize, and custom-comments length/box-style prompts get the same treatment.

I audited all ~124 completing-read / read-* call sites; the rest already named their operation and were left alone. These are prompt-string changes only, no logic touched.

9 files changed, 33 insertions, 18 deletions

diff --git a/modules/custom-comments.el b/modules/custom-comments.el
index 4e203f12b..b6919d651 100644
--- a/modules/custom-comments.el
+++ b/modules/custom-comments.el
@@ -236,7 +236,7 @@ Prompts for decoration character, text, and length option."
                        ""))
          (decoration-char (read-string "Decoration character (default =): " nil nil "="))
          (text (read-string "Comment text: "))
-         (length-option (completing-read "Length: "
+         (length-option (completing-read "Comment length: "
                                         '("fill-column" "half-column" "match-text")
                                         nil t nil nil "fill-column"))
          (length (cond
@@ -318,7 +318,7 @@ Prompts for decoration character, text, padding, and length option."
          (decoration-char (read-string "Decoration character (default =): " nil nil "="))
          (text (read-string "Comment text: "))
          (padding (string-to-number (read-string "Padding spaces (default 2): " nil nil "2")))
-         (length-option (completing-read "Length: "
+         (length-option (completing-read "Comment length: "
                                         '("fill-column" "half-column" "match-text")
                                         nil t nil nil "fill-column"))
          (length (cond
@@ -463,7 +463,7 @@ Prompts for decoration character, text, and length option."
                        ""))
          (decoration-char (read-string "Decoration character (default *): " nil nil "*"))
          (text (read-string "Comment text: "))
-         (length-option (completing-read "Length: "
+         (length-option (completing-read "Comment length: "
                                         '("fill-column" "half-column" "padded-text")
                                         nil t nil nil "fill-column"))
          (length (cond
@@ -545,10 +545,10 @@ Prompts for text, box style, and length option."
                          comment-end
                        ""))
          (text (read-string "Comment text: "))
-         (box-style (intern (completing-read "Box style: "
+         (box-style (intern (completing-read "Comment box style: "
                                              '("single" "double")
                                              nil t nil nil "single")))
-         (length-option (completing-read "Length: "
+         (length-option (completing-read "Comment length: "
                                         '("fill-column" "half-column" "padded-text")
                                         nil t nil nil "fill-column"))
          (length (cond
@@ -611,7 +611,7 @@ Prompts for decoration character, text, and length option."
                        (read-string "Block comment end (e.g., */): " nil nil "*/")))
          (decoration-char (read-string "Decoration character (default *): " nil nil "*"))
          (text (read-string "Comment text: "))
-         (length-option (completing-read "Length: "
+         (length-option (completing-read "Comment length: "
                                         '("fill-column" "half-column" "match-text")
                                         nil t nil nil "fill-column"))
          (length (cond
diff --git a/modules/dev-fkeys.el b/modules/dev-fkeys.el
index 00a467743..9fdfa5b3f 100644
--- a/modules/dev-fkeys.el
+++ b/modules/dev-fkeys.el
@@ -459,7 +459,7 @@ Prompts via `completing-read' between \"All tests\" (delegates to
 `cj/--f6-current-file-tests-impl')."
   (interactive)
   (let* ((candidates '("All tests" "Current file's tests"))
-         (label (completing-read "F6: " candidates nil t nil nil (car candidates))))
+         (label (completing-read "Run tests: " candidates nil t nil nil (car candidates))))
     (pcase label
       ("All tests" (projectile-test-project current-prefix-arg))
       ("Current file's tests"
diff --git a/modules/dirvish-config.el b/modules/dirvish-config.el
index 9e50bbc08..d92869669 100644
--- a/modules/dirvish-config.el
+++ b/modules/dirvish-config.el
@@ -78,7 +78,7 @@ Pure helper used by `cj/dired-ediff-files'."
          (pair (cj/--ediff-pair-from-files
                 (dired-get-marked-files)
                 (lambda ()
-                  (read-file-name "file: " (dired-dwim-target-directory)))
+                  (read-file-name "Ediff with file: " (dired-dwim-target-directory)))
                 #'file-newer-than-file-p)))
     (ediff-files (car pair) (cdr pair))
     (add-hook 'ediff-after-quit-hook-internal
diff --git a/modules/dwim-shell-config.el b/modules/dwim-shell-config.el
index 83f1d4a29..57eea7063 100644
--- a/modules/dwim-shell-config.el
+++ b/modules/dwim-shell-config.el
@@ -533,7 +533,7 @@ clipboard contents cannot inject shell commands."
   (defun cj/dwim-shell-commands-checksum ()
 	"Generate checksums for file(s) and save to .checksum file."
 	(interactive)
-	(let ((algorithm (completing-read "Algorithm: "
+	(let ((algorithm (completing-read "Checksum algorithm: "
 									  '("md5" "sha1" "sha256" "sha512")
 									  nil t)))
       (dwim-shell-command-on-marked-files
@@ -656,7 +656,7 @@ all marked files rather than once per file."
   (defun cj/dwim-shell-commands-compress-pdf ()
 	"Compress PDF file size."
 	(interactive)
-	(let ((quality (completing-read "Quality: "
+	(let ((quality (completing-read "PDF compression quality: "
 									'("screen" "ebook" "printer" "prepress")
 									nil t "ebook")))
       (dwim-shell-command-on-marked-files
@@ -677,7 +677,7 @@ all marked files rather than once per file."
 	"Convert text file to speech (audio file)."
 	(interactive)
 	(let ((voice (if (eq system-type 'darwin)
-					 (completing-read "Voice: " '("Alex" "Samantha" "Victoria" "Karen") nil t "Alex")
+					 (completing-read "Text-to-speech voice: " '("Alex" "Samantha" "Victoria" "Karen") nil t "Alex")
 				   "en")))
 	  (dwim-shell-command-on-marked-files
 	   "Text to speech"
@@ -917,7 +917,7 @@ gpg: decryption failed: No pinentry"
 											(symbol-name cmd)))
 										  cmd))
 								  commands))
-		   (selected (completing-read "Command: "
+		   (selected (completing-read "Run dwim-shell command: "
 									  command-alist
 									  nil
 									  t
diff --git a/modules/mu4e-org-contacts-integration.el b/modules/mu4e-org-contacts-integration.el
index 68f83dd21..6aed3d4cf 100644
--- a/modules/mu4e-org-contacts-integration.el
+++ b/modules/mu4e-org-contacts-integration.el
@@ -92,7 +92,7 @@ This bypasses the completion-at-point system for direct selection."
   (interactive)
   (when (mail-abbrev-in-expansion-header-p)
     (let* ((contacts (cj/get-all-contact-emails))
-           (selected (completing-read "Contact: " contacts nil t)))
+           (selected (completing-read "Insert contact email: " contacts nil t)))
       ;; If we're not at the beginning of a field, check if we need a comma
       (when (and (not (save-excursion
                         (skip-chars-backward " \t")
diff --git a/modules/org-agenda-config.el b/modules/org-agenda-config.el
index 3fa097081..e2b431f9a 100644
--- a/modules/org-agenda-config.el
+++ b/modules/org-agenda-config.el
@@ -259,7 +259,7 @@ scoped to that project's todo.org plus calendars, schedule, and inbox."
                                (file-exists-p (expand-file-name "todo.org" dir))))
                         all-dirs))
          (project-names (mapcar #'file-name-nondirectory project-dirs))
-         (chosen (completing-read "Project: " project-names nil t))
+         (chosen (completing-read "Show agenda for project: " project-names nil t))
          (todo-file (expand-file-name "todo.org"
                                       (expand-file-name chosen projects-dir)))
          (org-agenda-files (list todo-file
diff --git a/modules/org-config.el b/modules/org-config.el
index 7d66acfda..d2a0be34f 100644
--- a/modules/org-config.el
+++ b/modules/org-config.el
@@ -509,7 +509,7 @@ gains a date-only CLOSED line."
                (let ((default (if (member "DONE" org-done-keywords)
                                   "DONE"
                                 (car org-done-keywords))))
-                 (completing-read "Finalize as: " org-done-keywords
+                 (completing-read "Finalize task as: " org-done-keywords
                                   nil t nil nil default)))))
       (let ((org-inhibit-logging t))
         (org-todo finalized))           ; fires the journal-copy hook
diff --git a/modules/org-contacts-config.el b/modules/org-contacts-config.el
index bd39b6e87..d558245b6 100644
--- a/modules/org-contacts-config.el
+++ b/modules/org-contacts-config.el
@@ -148,7 +148,7 @@ Added: %U"
   (interactive)
   (find-file contacts-file)
   (goto-char (point-min))
-  (let ((contact (completing-read "Contact: "
+  (let ((contact (completing-read "Find contact: "
                                   (org-map-entries
                                    (lambda () (nth 4 (org-heading-components)))
                                    nil (list contacts-file)))))
@@ -226,7 +226,7 @@ For use outside of mu4e compose buffers. In mu4e, the integration
 module provides more sophisticated completion."
   (interactive)
   (let* ((items (cj/get-all-contact-emails))
-         (selected (completing-read "Contact: " items nil t)))
+         (selected (completing-read "Insert contact email: " items nil t)))
     (insert selected)))
 
 ;;; -------------------------------- Org Contacts --------------------------------
diff --git a/todo.org b/todo.org
index 6a268045b..7616e0ac6 100644
--- a/todo.org
+++ b/todo.org
@@ -2444,7 +2444,22 @@ Closing the ai-vterm with M-F9 while its window is in a split deletes the split
 *** 2026-06-02 Tue @ 14:12:48 -0500 Audit: still a bug, distinct from the F9 collapse
 The F9 toggle-off rework (38dad92) made F9 collapse the split by design, but that's the toggle path. This is M-F9 close (kills the agent process): close should leave the surrounding layout intact, not delete the sibling window. Craig confirmed it's still a bug. cj/--ai-vterm-close-buffer still calls delete-window.
 
-** TODO [#C] Separate dashboard navigator color from list items :feature:quick:solo:
+** DONE [#C] Descriptive completing-read prompts :feature:ux:
+CLOSED: [2026-06-02 Tue]
+:PROPERTIES:
+:LAST_REVIEWED: 2026-06-02
+:END:
+Reworded 17 picker prompts across 8 modules so each names the operation (C-f8 "Project:" → "Show agenda for project:", "F6:" → "Run tests:", the dwim-shell sub-prompts, both contact pickers, dirvish ediff, org finalize, and the custom-comments length/box-style prompts). Audited ~124 completing-read / read-* sites; the rest already named their operation.
+
+Audit every =completing-read= (and =read-*= picker) prompt in the config so the prompt names the operation about to happen, not just the kind of thing being chosen. The prompt is the only confirmation the user gets before committing to an action, so a generic one leaves a mis-keyed command ambiguous.
+
+Concrete trigger: C-f8 (project-filtered agenda) prompts just "Project". If Craig meant C-f9 (AI-vterm project picker) and hit C-f8 by accident, the bare "Project" prompt gives no signal which operation he's about to run — both pick a project, for different ends.
+
+Goal: each picker prompt makes the pending operation obvious, e.g. "Agenda for project: " vs "Open AI vterm for project: ". Sweep the call sites (grep =completing-read=, =read-directory-name=, =read-file-name=, =completing-read-multiple= across modules/), reword the ambiguous ones, keep the wording short.
+
+Filed 2026-06-02 from a C-f8/C-f9 mix-up. Priority set [#C] (UX polish) — re-grade if it deserves higher.
+
+
 :PROPERTIES:
 :LAST_REVIEWED: 2026-05-28
 :END: