docs-audit.yml

name: Docs Audit

# ---------------------------------------------------------------
# weekly docs audit -- reads all docs and checks for:
#   - outdated information vs official claude code docs
#   - missing cross-references between related docs
#   - missing "tested with" version stamps
#   - structural inconsistencies
#
# if issues found:
#   - ≤5 files changed: commits directly to main (trivial fixes)
#   - >5 files changed: opens a draft PR for review
# cost: ~$0.05-0.15 per run (haiku, larger context)
# ---------------------------------------------------------------

on:
  schedule:
    - cron: '0 10 * * 0'  # every sunday at 10:00 UTC
  workflow_dispatch:

permissions:
  contents: write
  pull-requests: write

concurrency:
  group: "docs-audit"
  cancel-in-progress: false

env:
  CLAUDE_MODEL: claude-haiku-4-5-20251001

jobs:
  audit:
    runs-on: ubuntu-latest
    timeout-minutes: 10
    steps:
      - uses: actions/checkout@v7

      - name: Check API key
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          if [ -z "$ANTHROPIC_API_KEY" ]; then
            echo "::warning::ANTHROPIC_API_KEY not available -- skipping audit"
            exit 1
          fi

      - name: Install Claude Code
        run: npm install -g @anthropic-ai/claude-code

      - name: Run docs audit
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          claude -p --model "$CLAUDE_MODEL" \
            "you are auditing the docs/ directory of the claude-code-tips repo.

          read every file in docs/, plugins/*/README.md, hooks/README.md, examples/agents/*.md, and examples/commands/*.md.

          check for:
          1. missing 'tested with' version stamps (every doc should have one)
          2. broken cross-references (links to files that dont exist)
          3. inconsistent structure (some docs have ## sections others dont)
          4. outdated CLI flags or tool names that dont match current claude code
          5. missing cross-references (e.g. hooks-guide should link to safety-guard.sh)

          important: only fix issues you can verify from the files in this repo. do not rely on your training data for current CLI flags or tool names -- if you're not sure, flag it but don't change it.

          for each issue found:
          - fix it directly in the file if you can (add missing stamps, fix links)
          - use lowercase voice, no fluff

          write a summary of all changes to /tmp/audit-findings.txt.
          if no issues found, write 'no issues found' to that file." \
            --allowedTools Read,Write,Edit,Glob,Grep

      - name: Commit or create PR depending on change size
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          if git diff --quiet && [ -z "$(git ls-files --others --exclude-standard)" ]; then
            echo "no changes from audit"
            exit 0
          fi

          git config user.name "docs-audit[bot]"
          git config user.email "docs-audit[bot]@users.noreply.github.com"
          git add docs/ plugins/ hooks/ examples/agents/ examples/commands/ 2>/dev/null || true
          git diff --cached --quiet && echo "nothing to commit" && exit 0

          CHANGED_FILES=$(git diff --cached --stat | tail -1 | grep -oE '[0-9]+ file' | grep -oE '[0-9]+')
          echo "files changed: $CHANGED_FILES"

          if [ "$CHANGED_FILES" -le 5 ]; then
            echo "≤5 files changed -- committing directly to main"
            git commit -m "docs: weekly audit fixes $(date +%Y-%m-%d)"
            git push origin main
          else
            echo ">5 files changed -- creating draft PR"

            # close any previous open docs-audit PRs (superseded)
            gh pr list --search "docs: weekly audit fixes" --state open --json number --jq '.[].number' | while read -r pr_number; do
              echo "closing superseded PR #$pr_number"
              gh pr close "$pr_number" --comment "superseded by newer docs audit run"
            done

            BRANCH="auto/docs-audit-$(date +%Y%m%d)"
            git checkout -b "$BRANCH"
            git commit -m "docs: weekly audit fixes $(date +%Y-%m-%d)"
            git push -u origin "$BRANCH"

            # use --body-file to avoid shell injection from LLM-generated content
            {
              echo "## automated docs audit"
              echo ""
              cat /tmp/audit-findings.txt 2>/dev/null || echo "see diff for details"
              echo ""
              echo "---"
              echo "automated -- review before merging."
            } > /tmp/pr-body.md

            if ! gh pr create \
              --title "docs: weekly audit fixes $(date +%Y-%m-%d)" \
              --body-file /tmp/pr-body.md \
              --base main \
              --draft; then
              echo "::warning::PR creation failed -- changes are on branch $BRANCH"
            fi
          fi