diff --git a/src/resources/extensions/sf/doctor.ts b/src/resources/extensions/sf/doctor.ts
index 044746fdf..a80f9048d 100644
--- a/src/resources/extensions/sf/doctor.ts
+++ b/src/resources/extensions/sf/doctor.ts
@@ -104,9 +104,13 @@ export {
 const TITLE_DELIMITER_RE = /[\u2014\u2013/]/; // em dash, en dash, forward slash
 
 /**
- * Check whether a milestone or slice title contains characters that conflict
- * with SF's state document delimiter conventions.
- * Returns a human-readable description of the problem, or null if the title is safe.
+ * Validate milestone/slice title against SF state document delimiters.
+ *
+ * Flags titles containing em/en dashes or forward slashes, which corrupt
+ * state documents and branch names. Returns human-readable error or null if safe.
+ *
+ * @param title \u2014 the milestone or slice title to validate
+ * @returns error description or null if title is safe
  */
 export function validateTitle(title: string): string | null {
 	if (TITLE_DELIMITER_RE.test(title)) {