audit-documentation

Audit Documentation

Compare recently shipped features against USER_GUIDE.md, README.md, and docs/index.md. File GitHub issues for documentation gaps and close existing documentation issues whose gaps are now covered.

Usage

/audit-documentation                  # Scan issues closed in the last 30 days
/audit-documentation --since v0.0.20  # Scan issues referenced in commits since a tag

Known limitation: Rate limits may apply for repos with hundreds of closed issues. The tag-based mode may miss issues if their PRs used Fixes or bare URLs instead of Closes #NNN.

Steps

Step 1 — Parse arguments and pre-flight

Detect whether --since <tag> was provided:

# Tag-based mode
TAG="v0.0.20"  # extracted from --since argument

# Validate tag exists locally
git rev-parse --verify "refs/tags/$TAG" 2>/dev/null
if [ $? -ne 0 ]; then
  # Try fetching tags and retry
  git fetch --tags origin
  git rev-parse --verify "refs/tags/$TAG" 2>/dev/null || {
    echo "Error: tag '$TAG' not found locally or on origin. Aborting."
    exit 1
  }
fi

For the default 30-day mode, compute the cutoff date using Python (portable across macOS and Linux):

CUTOFF_DATE=$(python3 -c "from datetime import datetime,timedelta; print((datetime.now()-timedelta(days=30)).strftime('%Y-%m-%d'))")
echo "Scanning issues closed since: $CUTOFF_DATE"

Step 2 — Discover source issues

Tag-based mode (two-pass):

Pass 1 — extract issue numbers from commit messages since the tag:

git log "$TAG..HEAD" --format="%s%n%b" | grep -oE '#[0-9]+' | grep -oE '[0-9]+' | sort -u

Pass 2 — get the tag's commit date, then find merged PRs since that date and extract Closes #NNN references:

TAG_DATE=$(git log -1 --format="%ci" "refs/tags/$TAG" | cut -d' ' -f1)
gh pr list -R handarbeit/fabrik --state merged \
  --search "merged:>=$TAG_DATE" \
  --json number,body \
  --limit 500 \
  --jq '.[] | .body' \
  | grep -oiE '(closes|fixes|resolves) #[0-9]+' \
  | grep -oE '[0-9]+' \
  | sort -u