fix(doc-guardian): use passive wording and add debouncing to reduce interruptions #291

lmiranda · 2026-01-29T01:33:09Z

lmiranda commented

2026-01-29 01:33:09 +00:00

Summary

Changed hook message from actionable "update needed" to passive "drift queued"
Added 5-second debouncing to prevent rapid-fire notifications during batch edits
Added queue clearing step to /doc-sync command documentation

Problem

The doc-guardian PostToolUse hook was causing workflow interruptions:

Actionable language ("update needed") triggered Claude to seek user confirmation
Rapid edits (4+ in sequence) generated multiple notifications, each potentially pausing workflow

Solution

Passive wording: Message now reads [doc-guardian] drift queued: ... instead of update needed
Debouncing: Same-type edits within 5 seconds are silently queued (still tracked, no notification)
Queue clearing: Added explicit step to clear queue after successful /doc-sync

Test plan

Edit multiple files in commands/ directory rapidly - should see only 1 notification
Wait 6+ seconds, edit another file - should see new notification
Verify queue file still accumulates all edits (count increases)
Run /doc-sync and verify queue is cleared

Note

Issue #287 also mentions URL restriction behavior, but this was not found in the current codebase. It may have been caused by a different component or already fixed. This PR addresses issues 1 and 2 from the issue.

Fixes #287

🤖 Generated with Claude Code

## Summary - Changed hook message from actionable "update needed" to passive "drift queued" - Added 5-second debouncing to prevent rapid-fire notifications during batch edits - Added queue clearing step to `/doc-sync` command documentation ## Problem The doc-guardian PostToolUse hook was causing workflow interruptions: 1. Actionable language ("update needed") triggered Claude to seek user confirmation 2. Rapid edits (4+ in sequence) generated multiple notifications, each potentially pausing workflow ## Solution 1. **Passive wording**: Message now reads `[doc-guardian] drift queued: ...` instead of `update needed` 2. **Debouncing**: Same-type edits within 5 seconds are silently queued (still tracked, no notification) 3. **Queue clearing**: Added explicit step to clear queue after successful `/doc-sync` ## Test plan - [ ] Edit multiple files in `commands/` directory rapidly - should see only 1 notification - [ ] Wait 6+ seconds, edit another file - should see new notification - [ ] Verify queue file still accumulates all edits (count increases) - [ ] Run `/doc-sync` and verify queue is cleared ## Note Issue #287 also mentions URL restriction behavior, but this was not found in the current codebase. It may have been caused by a different component or already fixed. This PR addresses issues 1 and 2 from the issue. Fixes #287 🤖 Generated with [Claude Code](https://claude.ai/code)

lmiranda added the Type/Bug Priority/Medium labels 2026-01-29 01:33:09 +00:00

lmiranda added 1 commit 2026-01-29 01:33:10 +00:00

fix(doc-guardian): use passive wording and add debouncing to reduce interruptions 1dad393eaf

The PostToolUse hook was causing workflow interruptions because:
1. Actionable language ("update needed") triggered Claude to seek confirmation
2. Rapid edits (4+ in sequence) generated multiple notifications

Changes:
- Message changed from "update needed" to "drift queued" (passive, informational)
- Added 5-second debouncing: same-type edits within window are silently queued
- Added queue clearing step to doc-sync.md command

Note: Issue #287 also mentions URL restriction behavior, but this was not
found in the current codebase - may have been a different component or
already fixed. Marking as partial fix.

Fixes #287

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

lmiranda referenced this pull request

2026-01-29 01:33:26 +00:00

fix(doc-guardian): Hook blocks workflow and fires excessively #287

lmiranda merged commit ba4db941ab into development

2026-01-29 01:34:43 +00:00

lmiranda deleted branch fix/issue-287-doc-guardian-hook-wording

2026-01-29 01:34:44 +00:00

lmiranda referenced this issue from a commit

2026-01-29 01:34:45 +00:00

Merge pull request 'fix(doc-guardian): use passive wording and add debouncing to reduce interruptions' (#291) from fix/issue-287-doc-guardian-hook-wording into development

Sign in to join this conversation.