Merge pull request #489 from authzed/suggestion-workflow-improvements

Suggestion workflow improvements

Author: samkim

.github/workflows/cla.yaml

@@ -1,6 +1,6 @@
 ---
 name: "CLA"
-on: # yamllint disable-line rule:truthy
+"on":
   issue_comment:
     types:
       - "created"

.github/workflows/claude-code-review.yml

@@ -3,13 +3,14 @@ name: "Claude Code Review"
 
 "on":
   pull_request:
-    types: ["opened", "synchronize", "ready_for_review", "reopened", "labeled", "edited"]
-    # Optional: Only run on specific file changes
-    # paths:
-    #   - "src/**/*.ts"
-    #   - "src/**/*.tsx"
-    #   - "src/**/*.js"
-    #   - "src/**/*.jsx"
+    types:
+      ["opened", "synchronize", "ready_for_review", "reopened", "labeled", "edited"]
+      # Optional: Only run on specific file changes
+      # paths:
+      #   - "src/**/*.ts"
+      #   - "src/**/*.tsx"
+      #   - "src/**/*.js"
+      #   - "src/**/*.jsx"
 
 jobs:
   claude-review:

.github/workflows/claude.yml

@@ -59,6 +59,9 @@ jobs:
 
   suggestion:
     name: "Suggestion Handler"
+    concurrency:
+      group: "doc-suggestion-${{ github.event.issue.number || inputs.issue_number }}"
+      cancel-in-progress: false
     if: |
       (github.event_name == 'issues' &&
        github.event.action == 'labeled' &&
@@ -93,13 +96,14 @@ jobs:
         # Configured to give 50 turns to claude based on observations. This can be increased if we observe sessions failing to complete
       - name: "Run Claude Code for Suggestion"
         id: "claude-suggestion"
+        timeout-minutes: 30
         uses: "anthropics/claude-code-action@v1"
         env:
           ISSUE_NUMBER: "${{ github.event_name == 'workflow_dispatch' && inputs.issue_number || github.event.issue.number }}"
         with:
           anthropic_api_key: "${{ secrets.ANTHROPIC_API_KEY }}"
-          # Enabling this may expose secrets. Do not set to true on public repos
-          # https://github.com/anthropics/claude-code-action/blob/main/docs/security.md#%EF%B8%8F-full-output-security-warning
+          # Full output may expose secrets - do not enable on public repos
+          # See: https://github.com/anthropics/claude-code-action/blob/main/docs/security.md
           show_full_output: false
           prompt: |
             Read the repository documentation structure and the issue description for issue #${{ github.event_name == 'workflow_dispatch' && inputs.issue_number || github.event.issue.number }}.
@@ -118,11 +122,58 @@ jobs:
             7. Push your branch to origin using: git push -u origin <branch-name>
             8. Post a comment to issue #${{ github.event_name == 'workflow_dispatch' && inputs.issue_number || github.event.issue.number }} with:
                - Summary of changes made
+               - Highlight any actions attempted but did not have access to complete
                - Link to create a PR using: https://github.com/${{ github.repository }}/compare/<branch-name>?expand=1
                Use the gh CLI: gh issue comment ${{ github.event_name == 'workflow_dispatch' && inputs.issue_number || github.event.issue.number }} --body "<your comment>"
 
-            Focus only on documentation changes. Make app changes necessary to support the documentation such as adding visual components, icons, and structure.
-            Otherwise, do not modify application code, configuration files, or CI/CD workflows.
+            RESTRICTIONS:
+            - Only modify documentation files (.mdx, .md) in app/
+            - Only modify _meta.ts for navigation entries
+            - May add components to components/ for documentation display
+            - NEVER modify .github/, scripts/, or root config files (package.json, next.config.mjs, etc.)
+            - If the request is out of scope, comment explaining why
           claude_args: |
             --allowedTools "Read,Write,Edit,Bash(git:*),Bash(gh:*),WebFetch(domain:authzed.com)"
             --max-turns 50
+
+      - name: "Notify on failure"
+        if: "failure()"
+        continue-on-error: true
+        env:
+          GH_TOKEN: "${{ github.token }}"
+          ISSUE_NUMBER: "${{ github.event_name == 'workflow_dispatch' && inputs.issue_number || github.event.issue.number }}"
+          RUN_URL: "${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}"
+        run: |
+          # Don't fail if notification fails
+          gh issue comment "$ISSUE_NUMBER" --body "## Documentation Workflow Failed
+
+          The automated documentation workflow encountered an error and could not complete.
+
+          **Workflow run**: $RUN_URL
+
+          A maintainer will investigate. You can also check the workflow logs for details.
+
+          ---
+          *Automated notification from GitHub Actions*" || echo "::warning::Failed to post failure notification"
+
+      - name: "Notify on timeout/cancel"
+        if: "cancelled()"
+        continue-on-error: true
+        env:
+          GH_TOKEN: "${{ github.token }}"
+          ISSUE_NUMBER: "${{ github.event_name == 'workflow_dispatch' && inputs.issue_number || github.event.issue.number }}"
+          RUN_URL: "${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}"
+        run: |
+          gh issue comment "$ISSUE_NUMBER" --body "## Documentation Workflow Cancelled/Timed Out
+
+          The workflow was cancelled or timed out after 30 minutes.
+
+          **Possible causes:**
+          - Request is too complex (try breaking into smaller issues)
+          - Claude encountered a difficult decision
+          - External service was slow to respond
+
+          **Workflow run**: $RUN_URL
+
+          ---
+          *Automated notification from GitHub Actions*" || echo "::warning::Failed to post timeout notification"