Fix CI#

Automatically detect, analyze, and fix failing CI checks on the current branch's pull request.

Dependencies#

If any script fails with "command not found" during execution, run the dependency checker:

scripts/check-deps.sh

It reports missing tools with install instructions. Inform the user what is missing and how to install it, then stop until the user confirms the tools are installed. Do NOT run the checker proactively — only when a command-not-found error is encountered.

Workflow#

Step 1: Get CI Status#

Run the bundled script to fetch all failed checks:

scripts/get-ci-status.sh [pr-number]

If no PR number is provided, the script auto-detects from the current branch. Output is JSON with failed check names, run IDs, and job IDs.

Skip the ci-status check in the output — it is an aggregation gate that fails when any other job fails. Focus on the actual failing jobs.

Step 2: Fetch Failure Logs#

For each failed check, retrieve the failure logs using the run ID and job ID from step 1:

gh run view <run-id> --log-failed -j <job-id>

Analyze the log output to identify the root cause: lint errors, type errors, test assertion failures, timeout issues, environment problems, etc.

Step 3: E2E Test Special Handling#

When any Frontend App E2E Tests check has failed, perform these additional steps to gather rich diagnostic data:

3a. Download report artifacts:

scripts/download-e2e-reports.sh <run-id> /tmp/cypress-reports

This downloads all cypress-report-e2e-* artifacts and extracts them. Each parallel container (0-3) produces a separate report. Artifacts have 1-day retention — if expired, rely on the job logs from step 2 instead.

3b. Parse the Mochawesome reports:

python3 scripts/parse-e2e-report.py /tmp/cypress-reports/cypress-report-e2e-*

This extracts from the HTML reports:

• Failed test names, suites, and spec files
• Error messages and stack traces
• Paths to video recordings and screenshots of failures

3c. Review visual evidence:

• Read video files (.mp4) of failed tests to observe the actual user flow and where it breaks
• Read screenshot files if present
• Cross-reference the error messages with the spec files in frontend/app/cypress/e2e/

Step 4: Analyze and Plan Fixes#

Based on the gathered evidence, identify the root cause for each failure. Common categories:

Present the analysis and proposed fix to the user before making changes. Keep fixes minimal — do not refactor surrounding code.

Step 5: Apply Fixes and Verify Locally#

Apply the minimal code changes, then run the appropriate local verification:

Frontend changes:

cd frontend && pnpm lint:fix && pnpm format && pnpm types

Backend changes:

cd backend && poetry run black . && poetry run ruff check . && poetry run mypy --pretty .

For specific test failures, run the relevant test command locally if possible. See references/ci-jobs.md for per-job verification commands.

Step 6: Handoff#

After all fixes are verified locally, summarize what was changed and suggest running /my-finish to commit, push, and create/update the PR.

Reference#

For detailed information about each CI job (trigger rules, check names, commands, artifact formats):

Constraints#

• Always confirm the fix plan with the user before modifying code
• Keep changes minimal — fix only what is needed to pass CI
• Do not refactor, add features, or make "improvements" beyond the CI fix
• Communicate with the user in Chinese; think and search in English