docs-check

Docs Checkpoint

Ensures documentation hygiene is not missed.

Writes result to .checkpoints/docs-check.json.

Heuristics (v1)

• Docs-only change (only *.md, *.txt, or files under .claude/, .claude-plugin/, docs/, plugins/) → PASS
• Code change (anything else) → requires one of:
  • CHANGELOG.md updated, OR
  • an explicit bypass label on the issue (recommended): no-changelog

Why the bypass label? Some changes are internal/refactors and not user-facing. The label makes that decision explicit and searchable.

Workflow

Step 1: Identify Issue + Diff

You should be given an issue ID in the prompt (e.g. TabzChrome-abc).

Determine changed files:

git status --porcelain

# If clean, compare to main
git diff --name-only main...HEAD

# If not clean, prefer staged+unstaged
git diff --name-only
git diff --cached --name-only

Step 2: Decide PASS/FAIL

CHANGED=$( (git diff --name-only main...HEAD 2>/dev/null || true) ; git diff --name-only 2>/dev/null || true ; git diff --cached --name-only 2>/dev/null || true )
CHANGED=$(echo "$CHANGED" | sed '/^$/d' | sort -u)

# Docs-only patterns (v1)
if echo "$CHANGED" | grep -qvE '(\.md|\.markdown|\.txt)$' \
  && echo "$CHANGED" | grep -qvE '^(docs/|plugins/|\.claude/|\.claude-plugin/)'; then
  CODE_CHANGED=1
else
  CODE_CHANGED=0
fi

If CODE_CHANGED=1, check:

# Changelog modified?
git diff --name-only main...HEAD 2>/dev/null | grep -q '^CHANGELOG\.md$' && CHANGELOG_OK=1 || CHANGELOG_OK=0

# Issue has bypass label?
LABELS=$(bd show "$ISSUE_ID" --json 2>/dev/null | jq -r '.[0].labels[]?' 2>/dev/null || true)
echo "$LABELS" | grep -qx 'no-changelog' && BYPASS=1 || BYPASS=0

• If CHANGELOG_OK=1 OR BYPASS=1 → PASS
• Else → FAIL and ask for either a CHANGELOG.md entry or a no-changelog label.

Step 3: Write Checkpoint File

mkdir -p .checkpoints
cat > .checkpoints/docs-check.json << EOF
{
  "checkpoint": "docs-check",
  "timestamp": "$(date -Iseconds)",
  "passed": ${PASSED},
  "code_changed": ${CODE_CHANGED},
  "changelog_updated": ${CHANGELOG_OK},
  "bypass_label": ${BYPASS},
  "summary": "${SUMMARY}"
}
EOF