Ci Troubleshoot
Diagnose failed GitHub Actions runs for pi-agent-dashboard. Maps the 6-workflow taxonomy (ci.yml, ci-electron.yml, electron-build.yml, publish.yml, sync-release-version.yml, deploy-site.yml), walks the release pipeline (prepare→publish→electron→github-release with strict needs[] contract), surfaces known failure modes (lockfile mismatch, bad Node version, CHANGELOG already-versioned, npm publish ordering, no-bash-on-Windows lint, missing node-pty prebuilds, GO/NO-GO bundle-server guard), and shows how to read gh run logs and retrigger failed jobs. Use when a CI run is red, a release is stuck, a workflow won't dispatch, or you need to understand which workflow does what. For triggering a release see release-cut; for revoking one see release-revoke.
Get the complete skill folder, including its scripts and reference files.
When to use this skill
Use Ci Troubleshoot when an AI agent needs a reusable SKILL.md workflow for this job: Diagnose failed GitHub Actions runs for pi-agent-dashboard. Maps the 6-workflow taxonomy (ci.yml, ci-electron.yml, electron-build.yml, publish.yml, sync-release-version.yml, deploy-site.yml), walks the release pipeline (prepare→publish→electron→github-release with strict needs[] contract), surfaces known failure modes (lockfile mismatch, bad Node version, CHANGELOG already-versioned, npm publish ordering, no-bash-on-Windows lint, missing node-pty prebuilds, GO/NO-GO bundle-server guard), and shows how to read gh run logs and retrigger failed jobs. Use when a CI run is red, a release is stuck, a workflow won't dispatch, or you need to understand which workflow does what. For triggering a release see release-cut; for revoking one see release-revoke.
When not to use it
Skip Ci Troubleshoot when the task is outside the coding category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.
How to install
Where will you use it?
mkdir -p ~/.claude/skills/ci-troubleshoot # Save SKILL.md to ~/.claude/skills/ci-troubleshoot/SKILL.md
- Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/ci-troubleshoot/SKILL.md. For a shared project, commit the folder at .claude/skills/ci-troubleshoot/ instead.
- Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
- For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.
Full install guide for Claude, Cursor, and Codex →
Try a starter prompt
After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.
Use the Ci Troubleshoot skill for this task: Use Ci Troubleshoot when this documented workflow matches the task. Confirm any required inputs or files before making changes.
What supports this recommendation?
70/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.
- Documentation
- 77/100
- Practical detail
- 68/100
- Source evidence
- 61/100
- Source signals
- 70/100
Model compatibility evidence
- claudeuntested
No model-specific signal or recorded compatibility test was found.
- chatgptuntested
No model-specific signal or recorded compatibility test was found.
- geminiuntested
No model-specific signal or recorded compatibility test was found.
- copilotuntested
No model-specific signal or recorded compatibility test was found.
- llamauntested
No model-specific signal or recorded compatibility test was found.
- perplexityuntested
No model-specific signal or recorded compatibility test was found.
- mistraluntested
No model-specific signal or recorded compatibility test was found.
- grokuntested
No model-specific signal or recorded compatibility test was found.
Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.
What this skill does
# CI Troubleshoot
Diagnose CI failures for pi-agent-dashboard. The repo has 6 workflows arranged in two flows:
``` ┌─ FLOW 1: every push ───────────────────────────────┐ │ │ │ ci.yml │ │ ├─ ci (tests + lint + type-check) │ │ ├─ standalone-install-smoke-linux (matrix) │ │ └─ standalone-install-smoke-windows (matrix) │ │ │ │ deploy-site.yml (on push if site/** changed) │ │ │ └────────────────────────────────────────────────────┘
┌─ FLOW 2: release ──────────────────────────────────┐ │ │ │ publish.yml (push tag v* OR workflow_dispatch) │ │ ├─ prepare (bump, lockfile, CHANGELOG, │ │ │ commit, tag, push) │ │ ├─ publish (npm publish OIDC, ordered) │ │ ├─ electron (calls _electron-build.yml) │ │ │ needs: [prepare, publish] ← CRITICAL │ │ └─ github-release (creates Release, drops logs) │ │ needs: [prepare, publish, electron] │ │ │ │ sync-release-version.yml (on release published) │ │ └─ writes site/src/data/latest-release.json │ │ │ └────────────────────────────────────────────────────┘
┌─ MANUAL: smoke a feature branch's installer matrix ┐ │ │ │ ci-electron.yml (workflow_dispatch only) │ │ └─ calls _electron-build.yml with │ │ source_only_bundle=true │ │ │ │ Safety invariants (locked by repo-lint): │ │ - no npm publish, no GitHub Release, no tag push │ │ - version slug is a SemVer prerelease ranked │ │ BELOW base stable (electron-updater safe) │ │ │ └────────────────────────────────────────────────────┘ ```
Full per-workflow detail: [`references/workflow-taxonomy.md`](references/workflow-taxonomy.md).
## First moves — always run these
```bash npx tsx ./scripts/list-recent-runs.ts # last 10 runs across all workflows npx tsx ./scripts/list-recent-runs.ts --failed # only failed npx tsx ./scripts/show-failed-run.ts <run-id> # failed steps + log tails npx tsx ./scripts/show-failed-run.ts # most recent failed run ```
These wrap `gh run list`, `gh run view --log-failed`, and similar. You need `gh auth status` to be authenticated.
> Scripts are TypeScript (cross-platform). All invocations use `npx tsx` so they work on Linux, macOS, and Windows. `tsx` is already a project dep; `gh` CLI is cross-platform.
## Triage decision tree
``` Is the run red? │ ▼ Which workflow? │ ┌────┼────────────────────────┬───────────────────┐ │ │ │ │ ▼ ▼ ▼ ▼ ci.yml publish.yml ci-electron.yml │ │ │ ▼ ▼ ▼ Tests, lint, smoke Release flow — which job? On-demand Electron │ │ smoke (not publish) ▼ │ references/ ├─ prepare → see below common-failures.md ├─ publish → npm ordering ├─ electron → matrix leg └─ github-release → asset collision ```
## Release pipeline — `publish.yml`
The release flow runs 4 jobs strictly in this order:
``` prepare ──▶ publish ──▶ electron ──▶ github-release (deps (npm OIDC, (matrix (creates + tag) ordered) 6 legs) Release) ```
`needs:` chains lock this order. **Do not remove `needs: [prepare, publish]` from `electron`** — the electron build's bundled server runs `npm install` for `@blackbelt-technology/*`, which must already exist on npm. Locked by `packages/shared/src/__tests__/publish-workflow-contract.test.ts`.
Full walkthrough with per-job failure modes: [`references/release-pipeline.md`](references/release-pipeline.md).
## Known failure modes
Maintained in [`references/common-failures.md`](references/common-failures.md). Headline catalog:
| Failure | Where | Diagnosis | Fix | |---------|-------|-----------|-----| | `verify-lockfile-versions.mjs` fails | `prepare` | Cross-ref specifier in lockfile doesn't match bumped version | Regenerate lockfile + commit; or fix `scripts/sync-versions.js` | | CHANGELOG already has `## [X.Y.Z]` | `prepare` | You're re-dispatching with a version that was already promoted | Bump to a new version, or revert the CHANGELOG section | | `npm publish` 403 | `publish` | OIDC trusted publisher not configured for that package | Configure in npm web UI; or temporarily use NPM_TOKEN | | Electron matrix leg fails | `electron` | Missing prebuild for node-pty/better-sqlite3 on that OS/arch | Check `bundle-server.mjs` GO/NO-GO guard; rebuild prebuilds | | `shell: bash` on Windows runner | any | Lint test `no-bash-on-windows.test.ts` flags it | Remove `shell: bash` or guard with `if: runner.os != 'Windows'` | | Electron job missing `needs:` | repo-lint | `publish-workflow-contract.test.ts` failed | Restore `needs: [prepare, publish]` | | `Cannot find module @blackbelt-technology/...` in electron | `electron` | `publish` job didn't run or failed; bundled server can't resolve from npm | Check `publish` job — re-run only if it failed; never bypass | | Fastify crashes in bundled server smoke | any using node | Bad Node version pinned in workflow | Bump `node-version:` to ≥ 22.18.0 | | Loud-but-harmless `EADDRINUSE` in smoke | smoke job | Concurrent server spawns | Usually self-recovering; check next log lines | | `electron` + `github-release` SKIPPED despite green `publish` | `electron` | Tag-push path skips `tag-and-push`; a skipped needs-ancestor poisons electron's DEFAULT `if: success()` | Give `electron` explicit `if: ${{ !cancelled() && needs.publish.result == 'success' }}` (mirrors `publish`'s guard). First hit v0.6.1 | | `✗ koffi prebuild GO/NO-GO failed at ...koffi\build\koffi\win32_x64\koffi.node` | `electron` (both win32 legs) | [email protected] ships the prebuild at `@koromix/koffi-win32-x64/win32_x64/koffi.node`; the 2.x `koffi/build/...` path is never created | Update `bundle-server.mjs` guard to check the 3.x @koromix path first, 2.x fallback. First hit v0.6.1 | | arm64 NSIS smoke: `pi-dashboard.exe not found ... after 150s` | `electron` (win32-arm64) | x64 runner can't execute an arm64 `Setup.exe`/app, so silent install extracts nothing | Guard the NSIS install-smoke step `if: matrix.platform == 'win32' && matrix.arch == 'x64'`. arm64 installer still builds+ships. First hit v0.6.1 |
## Reading gh logs efficiently
```bash # Last 10 runs (all workflows, this branch) gh run list -L 10
# Last 5 failed runs across all workflows gh run list -L 50 | grep -E 'failure|cancelled' | head -5
# Get a specific run, only the failed steps gh run view <run-id> --log-failed
# Watch a running workflow (live tail) gh run watch <run-id>
# Re-run only the failed jobs (preserves successful ones, saves CI time) gh run rerun <run-id> --failed
# Re-run from scratch (rare; usually for flakes) gh run rerun <run-id> ```
`gh run view --log-failed` is the highest-leverage one — it pulls only failed-step output, which is what you want 95% of the time.
**Rerun gotcha (tag-push releases):** `gh run rerun <id> --failed` does NOT re-dispatch skipped downstream reusable-workflow jobs (e.g. `electron`) even after `publish` flips green — they stay `skipped`. After a smoke-**gate** flake on a tag-push release, re-push the tag for a clean single-pass run instead: `git push --delete origin vX.Y.Z && git push origin vX.Y.Z`. `publish` is idempotent (skips already-published packages), so re-pushing the tag is safe.
## When the failure is repo-lint
Repo-lint tests fail the `ci` job specifically. They're listed in `debug-dashboard/references/test-failure-triage.md` → "Repo-lint tests". Fix the file that violated the rule. **Don't loosen the lint** — each one exists because of a real regression.
## Related skills
- `release-cut` — trigger a release (cuts the tag that fires `publish.yml`) - `release-revoke` — rollback / yank a release - `debug-dashboard` — when the bug only reproduces locally - `implement` — back to writing the fix - `code-review` — review the fix before re-pushing
Intended uses
- Use Ci Troubleshoot when this documented workflow matches the task.
Implementation notes
- Review the source instructions and adapt inputs before running the workflow.
Try it, then tell us how it went
A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.