suggest-documentation.yml

# Local test: script/ci/documentation_prompt_local (requires Claude Code CLI and ANTHROPIC_API_KEY)
name: Documentation change suggestions

on:
  workflow_dispatch:
    inputs:
      anthropic_api_key:
        description: 'Anthropic API key'
        required: true
        type: string
      create_pr:
        description: 'Apply suggested doc changes and open a PR'
        required: false
        default: false
        type: boolean

jobs:
  suggest-documentation-changes:
    runs-on: ubuntu-latest
    timeout-minutes: 45
    permissions:
      contents: write

    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
          token: ${{ secrets.GITHUB_TOKEN }}

      - uses: actions/setup-node@v4
        with:
          node-version: '22'

      - name: Fetch master
        run: git fetch origin master

      - name: Mask API key
        if: ${{ inputs.anthropic_api_key != '' }}
        run: echo "::add-mask::${{ inputs.anthropic_api_key }}"

      - name: Run documentation impact analysis
        id: analyze
        env:
          ANTHROPIC_API_KEY: ${{ inputs.anthropic_api_key || secrets.ANTHROPIC_API_KEY }}
        run: |
          ALLOWED_TOOLS='Read Grep Glob "Bash(git diff *)" "Bash(git log *)" "Bash(git show *)" "Bash(cat *)"'
          if [ "${{ inputs.create_pr }}" = "true" ]; then
            ALLOWED_TOOLS="$ALLOWED_TOOLS Write Edit"
          fi
          claude -p \
            --max-turns 35 \
            --allowedTools $ALLOWED_TOOLS \
            <<'PROMPT' | tee "$GITHUB_STEP_SUMMARY"
          You are analyzing the jit_preloader repository (a Ruby gem for N+1 preloading in Rails) to recommend documentation updates.

          CONTEXT:
          - This workflow runs on a branch. Compare the current branch to origin/master to see what code changed.
          - Use: git diff origin/master...HEAD --name-only (and git diff origin/master...HEAD for full diffs) to list and inspect changes.
          - Repo structure: README.md (main user-facing docs), lib/ (gem code), spec/ (tests), jit_preloader.gemspec. No separate dev-docs or Confluence.

          YOUR TASK (two parts):

          PART 1 – Report
          For the code changes between this branch and master, identify what documentation should be updated or created. Consider:

          1. **README.md** – usage, installation, examples, and “What it doesn’t solve” / “Consequences” that might be affected or missing
          2. **Code documentation** – inline comments, YARD/rdoc in lib/, and method/class docs that should reflect new behaviour or APIs
          3. **Other** – CHANGELOG (if present), contributing guidelines, gem summary/description in jit_preloader.gemspec, or any other docs you think are relevant

          First, produce a clear structured report to stdout in this format:

          ## Documentation change suggestions

          ### 1. README.md
          - (bullet list of specific sections and suggested changes, or "None identified")

          ### 2. Code documentation
          - (bullet list of files in lib/ and suggested comment/YARD updates, or "None identified")

          ### 3. Other
          - (bullet list or "None identified")

          ### Summary
          (Short overall summary and priority if applicable.)

          PART 2 – Apply changes (only if you have Write and Edit available)
          If you have Write and Edit tools available: apply the documentation changes you recommended. Edit the actual files (README.md, files in lib/, etc.) so the docs match the code. If you identified no changes or only external/Confluence items, do nothing. Do NOT run any git commands (no commit, push, or branch); the workflow will create the branch and PR.

          RULES:
          - Use only Read, Grep, Glob, and the allowed Bash commands to explore; base recommendations on the actual diff (origin/master...HEAD). If there are no code changes, say so and do not edit.
          - Be specific in the report (e.g. "Update README: add section on X because the API now does Y").
          - If the change is purely refactor or trivial and needs no doc updates, say that and do not edit.

          Start by running the git diff commands to see what changed, then read the relevant changed files and existing docs, then write your report, then (if you have Write/Edit) apply the changes.
          PROMPT

      - name: Check for documentation changes
        if: inputs.create_pr
        id: changes
        run: |
          if [ -n "$(git status --porcelain)" ]; then
            echo "has_changes=true" >> "$GITHUB_OUTPUT"
          else
            echo "has_changes=false" >> "$GITHUB_OUTPUT"
          fi

      - name: Create branch and PR with documentation updates
        if: inputs.create_pr && steps.changes.outputs.has_changes == 'true'
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          BRANCH="docs/suggested-updates-${GITHUB_REF_NAME//\//-}"
          git checkout -b "$BRANCH"
          git add -A
          git commit -m "Apply suggested documentation updates"
          git push origin "$BRANCH"
          gh pr create \
            --base "$GITHUB_REF_NAME" \
            --head "$BRANCH" \
            --title "Suggested documentation updates" \
            --body "Auto-generated from documentation impact analysis. Review the diff and the [workflow run summary](${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}/actions/runs/${GITHUB_RUN_ID}) for context."