1

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

Leo Miranda edited this page 2026-01-29 01:36:24 +00:00

Table of Contents

• Context
• Problem
• Solution
• Prevention
• Related

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: fix(doc-guardian): Hook blocks workflow and fires excessively (#287)
• PR: fix(doc-guardian): use passive wording and add debouncing to reduce interruptions (#291)

---

Tags: hook, doc-guardian, wording, non-blocking, debouncing, ux