personal-projects/leo-claude-mktplace
Template
0
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
Reviewed-on: #291
This commit was merged in pull request #291.
This commit is contained in:
Leo Miranda
2026-01-29 01:34:43 +00:00
parent d8971efafe 1dad393eaf
commit ba4db941ab
2 changed files with 38 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
plugins/doc-guardian/commands/doc-sync.md
View File

@@ -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

33
plugins/doc-guardian/hooks/notify.sh
View File

@@ -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