From 1dad393eaf63b186be2af98a639cc2ff3813d1db Mon Sep 17 00:00:00 2001
From: lmiranda <leobmiranda@gmail.com>
Date: Wed, 28 Jan 2026 20:32:46 -0500
Subject: [PATCH] fix(doc-guardian): use passive wording and add debouncing to
 reduce interruptions

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>
---
 plugins/doc-guardian/commands/doc-sync.md |  8 +++++-
 plugins/doc-guardian/hooks/notify.sh      | 33 +++++++++++++++++++++--
 2 files changed, 38 insertions(+), 3 deletions(-)

diff --git a/plugins/doc-guardian/commands/doc-sync.md b/plugins/doc-guardian/commands/doc-sync.md
index 5805a1f..5cae98d 100644
--- a/plugins/doc-guardian/commands/doc-sync.md
+++ b/plugins/doc-guardian/commands/doc-sync.md
@@ -52,7 +52,13 @@ Then proceed with the sync.
    - Single commit: `docs: sync documentation with code changes`
    - Include summary of what was updated in commit body
 
-5. **Output**
+5. **Clear Queue**
+   After successful sync, clear the queue file:
+   ```bash
+   echo "# Doc Guardian Queue - cleared after sync on $(date +%Y-%m-%d)" > .doc-guardian-queue
+   ```
+
+6. **Output**
 ```
 ## Documentation Sync Complete
 
diff --git a/plugins/doc-guardian/hooks/notify.sh b/plugins/doc-guardian/hooks/notify.sh
index 8511fb8..e4624be 100755
--- a/plugins/doc-guardian/hooks/notify.sh
+++ b/plugins/doc-guardian/hooks/notify.sh
@@ -2,6 +2,10 @@
 # doc-guardian notification hook
 # Tracks documentation dependencies and queues updates
 # This is a command hook - guaranteed not to block workflow
+#
+# IMPORTANT: Output is purely informational - uses passive language
+# to avoid triggering Claude to seek user confirmation.
+# Run /doc-sync to process the queue when ready.
 
 # Read tool input from stdin (JSON with file_path)
 INPUT=$(cat)
@@ -44,6 +48,30 @@ DEPENDENT_DOCS="${DOC_DEPS[$MODIFIED_TYPE]}"
 # Queue file for tracking pending updates
 QUEUE_FILE="${CLAUDE_PROJECT_ROOT:-.}/.doc-guardian-queue"
 
+# Debounce: skip notification if same type was logged in last 5 seconds
+# This prevents 4+ rapid notifications during batch edits
+DEBOUNCE_SECONDS=5
+if [ -f "$QUEUE_FILE" ]; then
+    LAST_ENTRY=$(tail -1 "$QUEUE_FILE" 2>/dev/null || true)
+    LAST_TYPE=$(echo "$LAST_ENTRY" | cut -d'|' -f2 | tr -d ' ')
+    LAST_TIME=$(echo "$LAST_ENTRY" | cut -d'|' -f1 | tr -d ' ')
+
+    if [ "$LAST_TYPE" = "$MODIFIED_TYPE" ] && [ -n "$LAST_TIME" ]; then
+        # Convert timestamps to seconds for comparison
+        LAST_EPOCH=$(date -d "$LAST_TIME" +%s 2>/dev/null || echo "0")
+        NOW_EPOCH=$(date +%s)
+        DIFF=$((NOW_EPOCH - LAST_EPOCH))
+
+        if [ "$DIFF" -lt "$DEBOUNCE_SECONDS" ]; then
+            # Still add to queue, but skip notification
+            {
+                echo "$(date +%Y-%m-%dT%H:%M:%S) | $MODIFIED_TYPE | $FILE_PATH | $DEPENDENT_DOCS"
+            } >> "$QUEUE_FILE" 2>/dev/null || true
+            exit 0
+        fi
+    fi
+fi
+
 # Add to queue (create if doesn't exist, append if does)
 {
     echo "$(date +%Y-%m-%dT%H:%M:%S) | $MODIFIED_TYPE | $FILE_PATH | $DEPENDENT_DOCS"
@@ -52,7 +80,8 @@ QUEUE_FILE="${CLAUDE_PROJECT_ROOT:-.}/.doc-guardian-queue"
 # Count pending updates
 PENDING_COUNT=$(wc -l < "$QUEUE_FILE" 2>/dev/null | tr -d ' ' || echo "1")
 
-# Output notification with specific docs that need updating
-echo "[doc-guardian] $MODIFIED_TYPE changed → update needed: $DEPENDENT_DOCS (${PENDING_COUNT} pending)"
+# Output passive notification (no action implied)
+# Uses "queued" instead of "update needed" to avoid triggering Claude to ask about it
+echo "[doc-guardian] drift queued: $MODIFIED_TYPE → $DEPENDENT_DOCS ($PENDING_COUNT total)"
 
 exit 0