Add "lessons/patterns/hook-message-wording-affects-claude-continuation-behavior"

lessons%2Fpatterns%2Fhook-message-wording-affects-claude-continuation-behavior.-.md

@@ -0,0 +1,31 @@
+## Context
+
+- doc-guardian PostToolUse hook was outputting notifications on file edits
+- Hook was technically correct: command type, exit 0, plain text output
+- Users reported workflow interruptions requiring "move forward" to continue
+
+## Problem
+
+The message "update needed" triggered Claude to seek user confirmation before proceeding, even though the hook was non-blocking by design. Additionally, rapid edits caused 4+ notifications in sequence.
+
+## Solution
+
+1. Changed message wording from actionable ("update needed") to passive ("drift queued")
+2. Added 5-second debouncing to batch rapid-fire notifications
+3. PR #291 merged into development
+
+## Prevention
+
+When writing hook output messages:
+- Use passive/informational language, not actionable language
+- Avoid words like "needed", "required", "must", "should"
+- Prefer "queued", "noted", "logged", "tracked"
+- Consider debouncing for hooks that fire on frequent events (Edit, Write)
+
+## Related
+
+- Issue: #287
+- PR: #291
+
+---
+**Tags:** hook, doc-guardian, wording, non-blocking, debouncing, ux