From 33475e7b5978bd38939529b2dbc483c531adcf03 Mon Sep 17 00:00:00 2001 From: Leo Miranda Date: Thu, 29 Jan 2026 01:36:24 +0000 Subject: [PATCH] Add "lessons/patterns/hook-message-wording-affects-claude-continuation-behavior" --- ...-affects-claude-continuation-behavior.-.md | 31 +++++++++++++++++++ 1 file changed, 31 insertions(+) create mode 100644 lessons%2Fpatterns%2Fhook-message-wording-affects-claude-continuation-behavior.-.md diff --git a/lessons%2Fpatterns%2Fhook-message-wording-affects-claude-continuation-behavior.-.md b/lessons%2Fpatterns%2Fhook-message-wording-affects-claude-continuation-behavior.-.md new file mode 100644 index 0000000..c9d2090 --- /dev/null +++ b/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 \ No newline at end of file