Cursor rule

1---
2description: When the Github Actions build is broken
3alwaysApply: false
4version: 1.0.0
5---
6 
7# Fixing Broken GitHub Actions Builds
8 
9## Purpose
10 
11This guide documents the process for diagnosing and fixing broken GitHub Actions builds
12using the `gh` CLI.
13 
14## Prerequisites
15 
16### Check if gh is installed
17 
18First, verify the GitHub CLI is installed:
19 
20```bash
21gh --version
22```
23 
24### If gh is not installed
25 
26Politely stop and guide the developer:
27 
28> The GitHub CLI (`gh`) is not installed. Let's get that set up first!
29>
30> Installation (macOS):
31>
32> ```bash
33> brew install gh
34> gh auth login
35> ```
36>
37> Follow the prompts to authenticate with GitHub. Once complete, we can proceed with
38> debugging the build!
39 
40## Diagnostic Workflow
41 
42### Step 1: List Recent Workflow Runs
43 
44```bash
45gh run list --limit 5
46```
47 
48Identify the failed run (marked with `X` or `failure` status). Note the run ID.
49 
50### Step 2: Get Failed Logs
51 
52```bash
53gh run view <run-id> --log-failed | cat
54```
55 
56This shows ONLY the logs from failed steps. Analyze these logs to identify the root
57cause.
58 
59### Step 3: Reproduce Locally
60 
61Based on the error in the logs, reproduce the failure locally to verify the fix.
62 
63### Step 4: Make the Fix
64 
65Edit the relevant files to fix the issue identified in the logs.
66 
67### Step 5: Verify Locally
68 
69Test the fix thoroughly to ensure it resolves the issue.
70 
71### Step 6: Report to Developer
72 
73DO NOT commit or push changes!
74 
75Report to the developer:
76 
77> Build issue fixed!
78>
79> Changes made:
80>
81> - `path/to/file`: Description of change
82>
83> Next steps:
84>
85> 1. Review the changes with `git status` and `git diff`
86> 2. Test locally if desired
87> 3. Commit and push when ready
88> 4. Monitor the new build with `gh run watch`
89 
90## Integration with Cursor
91 
92When a developer says "the build is broken" or "fix the GitHub Actions build":
93 
941. Run `gh --version` to verify installation (stop if not installed)
952. Run `gh run list --limit 5` to see recent runs
963. Identify the failed run ID
974. Run `gh run view <run-id> --log-failed | cat` to get error details
985. Analyze the logs and identify root cause
996. Fix the issue locally
1007. Verify the fix works
1018. Report back to developer with changes and next steps
102 
103Remember: We diagnose and fix, the developer commits and pushes!
104