Fix Workflow

Phase 3: Diagnose Each Failed Run

Process each failed run sequentially:

3a: Gather context

• gh run view <id> --json workflowName,headBranch,headSha,conclusion,jobs,url
• gh run view <id> --log-failed — capture the error output
• If --log-failed returns empty, report: "Logs unavailable — re-run with gh run rerun <id>" and skip this run.

3b: Match to workflow file

• Read each .github/workflows/*.yml in the repo. Match by comparing the YAML name: field to the workflowName from the run JSON. If no match by name, try matching by filename.

3c: Identify failing step

• From the --log-failed output, identify which job and step failed.
• In the matched workflow YAML, find that step. Extract its run: command and working-directory (or the job-level defaults.run.working-directory).

3d: Classify the step

• Locally reproducible (code fix): Step has a run: key, does not reference ${{ secrets.* }}, does not connect to remote services, AND the failure is caused by code that can be fixed (e.g., type errors, test failures, lint issues, build errors).
• Environment mismatch: Step has a run: key and is locally reproducible, BUT the failure is caused by a difference between the local dev environment and CI — not by the code itself. Signals: the command succeeds locally but fails in CI, or the error references version mismatches, missing system deps, or lock file sync issues (e.g., npm ci failing because package-lock.json was generated by a different npm version).
• Infrastructure-only: Step uses uses: (a GitHub Action), references secrets, or connects to remote services.
• Consult REFERENCE.md for classification guidance and edge cases.

Phase 4: Fix or Report

Locally reproducible failures (code fix)

1. Run the extracted command in the correct working directory (relative to repo root).
2. Analyze the local error output. Read the relevant source files, understand the root cause.
3. Apply the fix directly to the source files.
4. Re-run the same command to verify the fix works.
5. If the fix fails, iterate (max 3 attempts). After 3 failures, fall back to reporting.
6. If --dry-run, skip steps 3-5 and report what you would fix.

Environment mismatch failures

Do NOT attempt a code fix — the code is fine, the environment is wrong. Diagnose the mismatch and report:

• What differs between local and CI (Node/npm version, OS, system deps, etc.)
• What caused the drift (e.g., lock file regenerated by a different npm version)
• Actionable fix steps (e.g., install a version manager, pin the runtime version, regenerate lock file with the correct toolchain)
• Check for .nvmrc, .node-version, engines field in package.json, or similar version pinning — suggest adding one if missing.

Infrastructure-only failures

Do NOT attempt to fix. Generate a report with:

• Workflow name, run URL, branch, failing step name
• Error message from the logs
• Root cause hypothesis
• Actionable steps (see REFERENCE.md for common remediation patterns)

Phase 5: Summary

Fix Workflow complete
Fixed: N | Reported: N | Skipped: N

Fixed:
- [workflow] step "X" on branch Y — one-line description of fix

Needs manual action:
- [workflow] step "X" on branch Y — one-line description + action

Files modified: [list]

Remind the user: "Fixes applied to working tree but NOT committed. Review with git diff."

Error Handling

• gh not authenticated: Stop with instructions to run gh auth login
• No workflow files found: Stop with "No .github/workflows/ directory found"
• Logs expired/empty: Skip run, suggest gh run rerun <id>
• Fix attempts exhausted: Fall back to actionable report