Enhance dead link checker to create LLM-actionable issues

- Parse lychee report to extract specific broken links with file locations
- Create structured issues with clear fix instructions for each broken link
- Format issue body to be easily parseable by LLMs for automated fixes
- Add PR commenting for link check failures during pull requests

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

Author: ironicbadger

.github/workflows/check-links.yml

@@ -54,13 +54,90 @@ jobs:
           name: link-check-report
           path: lychee-report.md
 
-      - name: Create issue from failed link check
+      - name: Create actionable issue for broken links
         if: failure() && github.event_name == 'schedule'
-        uses: peter-evans/create-issue-from-file@v5
+        uses: actions/github-script@v7
         with:
-          title: "Broken links detected in documentation"
-          content-filepath: ./lychee-report.md
-          labels: |
-            documentation
-            broken-links
-            automated
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            const fs = require('fs');
+            const report = fs.readFileSync('./lychee-report.md', 'utf8');
+            
+            // Parse the lychee report to extract broken links
+            const lines = report.split('\n');
+            const brokenLinks = [];
+            let currentFile = '';
+            
+            for (const line of lines) {
+              // Match file paths in the report
+              if (line.includes('.md') && !line.includes('|')) {
+                currentFile = line.trim().replace(/^\*\*/, '').replace(/\*\*$/, '');
+              }
+              // Match broken links
+              if (line.includes('[') && line.includes('](') && line.includes('Failed')) {
+                const match = line.match(/\[.*?\]\((.*?)\)/);
+                if (match) {
+                  brokenLinks.push({
+                    file: currentFile,
+                    url: match[1],
+                    line: line.trim()
+                  });
+                }
+              }
+            }
+            
+            const issueBody = `## Broken Links Detected
+            
+            The automated link checker found ${brokenLinks.length} broken link(s) in the documentation that need to be fixed.
+            
+            ### Instructions for fixing:
+            
+            Please update the following broken links in the documentation files. For each broken link, either:
+            1. Update the URL to the correct destination
+            2. Remove the link if it's no longer relevant
+            3. Replace with an archived version from Wayback Machine if appropriate
+            
+            ### Broken Links to Fix:
+            
+            ${brokenLinks.map((link, index) => 
+              `${index + 1}. **File:** \`${link.file}\`
+               **Broken URL:** ${link.url}
+               **Action:** Find this URL in the file and update or remove it
+            `).join('\n')}
+            
+            ### Full Report:
+            
+            <details>
+            <summary>Click to see the full lychee report</summary>
+            
+            \`\`\`
+            ${report}
+            \`\`\`
+            
+            </details>
+            
+            ---
+            *This issue was automatically generated by the dead link checker workflow.*`;
+            
+            await github.rest.issues.create({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              title: `Fix ${brokenLinks.length} broken link(s) in documentation`,
+              body: issueBody,
+              labels: ['documentation', 'broken-links', 'automated', 'good first issue']
+            });
+            
+      - name: Comment PR with link check results
+        if: failure() && github.event_name == 'pull_request'
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            const fs = require('fs');
+            const report = fs.readFileSync('./lychee-report.md', 'utf8');
+            await github.rest.issues.createComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+              body: `## ❌ Dead Links Found\n\n${report}\n\nPlease fix these broken links before merging.`
+            });