bot-write-docs.yml

name: Wheels Bot — Write Docs

# Phase 4 (auto-fire): runs from wheels-bot[bot] comments containing
# `wheels-bot:docs-confidence:high` OR `wheels-bot:docs-confidence:medium`
# (the docs-request path's auto-fire markers). Medium fires because
# write-docs has its own step-4 safety net for structural docs-architecture
# decisions (posts `wheels-bot:docs-held:<issue>` instead of opening a PR).
# workflow_dispatch is preserved for manual reruns.
on:
  issue_comment:
    types: [created]
  workflow_dispatch:
    inputs:
      issue-number:
        description: 'Issue number to write docs for'
        required: true
        type: string

permissions:
  contents: read

concurrency:
  group: wheels-bot-write-docs-${{ github.event.issue.number || inputs.issue-number }}
  cancel-in-progress: false

jobs:
  write-docs:
    name: Write docs
    runs-on: ubuntu-latest
    timeout-minutes: 30
    # Auto-fires from wheels-bot[bot] comments with docs-confidence:high
    # OR docs-confidence:medium. Low stays manual.
    # The bot-identity check is load-bearing: prevents humans from
    # triggering write-docs by quoting a marker in a reply.
    if: |
      vars.WHEELS_BOT_ENABLED == 'true'
      && (
        github.event_name == 'workflow_dispatch'
        || (github.event_name == 'issue_comment'
            && github.event.comment.user.login == 'wheels-bot[bot]'
            && (contains(github.event.comment.body, 'wheels-bot:docs-confidence:high')
                || contains(github.event.comment.body, 'wheels-bot:docs-confidence:medium')))
      )
    env:
      ISSUE_NUMBER: ${{ github.event.issue.number || inputs.issue-number }}
      WHEELS_CI: "true"
    steps:
      - name: Generate App token
        id: app-token
        uses: actions/create-github-app-token@v2
        with:
          app-id: ${{ secrets.WHEELS_BOT_APP_ID }}
          private-key: ${{ secrets.WHEELS_BOT_PRIVATE_KEY }}

      - name: Checkout develop
        uses: actions/checkout@v6
        with:
          ref: develop
          fetch-depth: 0
          token: ${{ steps.app-token.outputs.token }}

      - name: Skip check
        id: gate
        uses: ./.github/actions/wheels-bot-skip-check
        with:
          target-type: issue
          target-number: ${{ env.ISSUE_NUMBER }}
          marker-pattern: 'wheels-bot:write-docs:${{ env.ISSUE_NUMBER }}|wheels-bot:docs-held:${{ env.ISSUE_NUMBER }}'
          github-token: ${{ steps.app-token.outputs.token }}

      - name: Compute branch slug
        if: steps.gate.outputs.skip == 'false'
        id: branch
        env:
          GH_TOKEN: ${{ steps.app-token.outputs.token }}
        run: |
          set -euo pipefail
          title=$(gh issue view "$ISSUE_NUMBER" --json title --jq '.title')
          slug=$(echo "$title" | tr '[:upper:]' '[:lower:]' \
            | sed -E 's/[^a-z0-9]+/-/g; s/^-+//; s/-+$//' \
            | cut -c1-50 \
            | sed -E 's/-+$//')
          [[ -z "$slug" ]] && slug="issue"
          name="docs/bot-${ISSUE_NUMBER}-${slug}"
          echo "name=$name" >> "$GITHUB_OUTPUT"

      - name: Configure git + create branch
        if: steps.gate.outputs.skip == 'false'
        run: |
          git config user.name "wheels-bot[bot]"
          git config user.email "wheels-bot[bot]@users.noreply.github.com"
          git checkout -b "${{ steps.branch.outputs.name }}"

      - name: Run Write Docs
        if: steps.gate.outputs.skip == 'false'
        uses: anthropics/claude-code-action@v1
        with:
          # Triggered by wheels-bot[bot] comments containing a
          # docs-confidence:high or docs-confidence:medium marker.
          # Allow the bot identity (and github-actions[bot] for consistency).
          allowed_bots: 'wheels-bot[bot],github-actions[bot]'
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          github_token: ${{ steps.app-token.outputs.token }}
          prompt: |
            /write-docs ${{ env.ISSUE_NUMBER }}
          claude_args: |
            --model claude-sonnet-4-6
            --max-turns 300
            --allowedTools "Bash(gh:*),Bash(git status),Bash(git log:*),Bash(git diff:*),Bash(git show:*),Bash(git grep:*),Bash(git add:*),Bash(git commit:*),Bash(git push:*),Read,Edit,Write,Grep,Glob"

      - name: Push branch
        if: steps.gate.outputs.skip == 'false'
        env:
          GH_TOKEN: ${{ steps.app-token.outputs.token }}
        run: |
          # Only push if the bot actually committed doc changes; otherwise
          # the run was a no-op (e.g. write-docs hit its safety net).
          if git diff --quiet origin/develop -- && git diff --cached --quiet; then
            echo "No changes produced — nothing to push."
            exit 0
          fi
          git push -u origin "${{ steps.branch.outputs.name }}"