rudder-desktop-dev-recovery-maintainer
starsforks
How to install rudder-desktop-dev-recovery-maintainer?
undertone0809/rudder/rudder-desktop-dev-recovery-maintainer
$npx -y skills add Undertone0809/rudder --skill rudder-desktop-dev-recovery-maintainerUse when Rudder local Desktop development, Electron shell, embedded Postgres, ~/.rudder instance state, dev startup, update/install smoke, packaged boot, or release-blocking local Desktop validation fails or needs recovery.
SKILL.md
| 1 | # Rudder Desktop Dev Recovery Maintainer |
| 2 | |
| 3 | Use this skill to get the local Rudder Desktop development path back to a known |
| 4 | working state. |
| 5 | |
| 6 | This is not the release runbook. It is the recovery layer for local Desktop |
| 7 | startup, dev-shell runtime, embedded database state, update/install smoke, and |
| 8 | the handoff point before release work. |
| 9 | |
| 10 | ## Use When |
| 11 | |
| 12 | Use this skill for prompts like: |
| 13 | |
| 14 | - "`pnpm dev` 好像桌面端跑不起来了" |
| 15 | - "Desktop dev shell 起不来" |
| 16 | - "API 能访问，但桌面端没起来" |
| 17 | - "`pnpm dev` starts the API but Electron exits during a UI build/typecheck" |
| 18 | - "embedded Postgres / `~/.rudder` 状态是不是乱了" |
| 19 | - "update 最新版失败，先 debug 一下" |
| 20 | - "桌面端问题修完之后再发版" |
| 21 | - "我本地 Desktop 是不是指到错的 instance" |
| 22 | |
| 23 | Also use this when a release request is blocked by local Desktop validation. |
| 24 | Fix the local Desktop blocker first, then route the release to |
| 25 | `release-maintainer`. |
| 26 | |
| 27 | ## Do Not Use When |
| 28 | |
| 29 | Do not use this skill for: |
| 30 | |
| 31 | - npm/GitHub Release/tag/dist-tag publishing; use `release-maintainer` |
| 32 | - packaged-app verification after code changes with no startup failure; follow |
| 33 | the normal Desktop validation workflow |
| 34 | - stopping only a known repo-local dev runtime; use |
| 35 | `stop-rudder-dev-maintainer` |
| 36 | - ordinary web UI data diagnosis; use `rudder-data-path-diagnostician-maintainer` |
| 37 | - review-only of a Desktop feature; use `agent-work-reviewer-maintainer` |
| 38 | |
| 39 | If the user's first request is "发版" and Desktop is already healthy, do not |
| 40 | route through this skill. |
| 41 | |
| 42 | ## Default Workflow |
| 43 | |
| 44 | ### 1. Classify the failure mode |
| 45 | |
| 46 | Start with a short state packet: |
| 47 | |
| 48 | - `git status --short --branch` |
| 49 | - requested command, for example `pnpm dev`, `pnpm desktop:dev`, or |
| 50 | `pnpm desktop:verify` |
| 51 | - whether the failure is API server, Vite middleware, Electron shell, embedded |
| 52 | Postgres, UI build/typecheck, packaged smoke, update download, or app launch |
| 53 | - exact stderr/stdout excerpt and exit code |
| 54 | - currently listening ports around `3100` |
| 55 | - relevant `~/.rudder/instances/*` path when the process prints one |
| 56 | - whether the failing file is committed, modified, untracked, or part of a |
| 57 | broader dirty feature set |
| 58 | |
| 59 | Do not guess from memory when the command can be rerun safely. |
| 60 | |
| 61 | ### 2. Read the local Desktop contract |
| 62 | |
| 63 | Read only the relevant docs and scripts: |
| 64 | |
| 65 | - `doc/engineering/DEVELOPING.md` |
| 66 | - `doc/engineering/DESKTOP.md` |
| 67 | - `doc/README.md` for navigation when needed |
| 68 | - `desktop/package.json` |
| 69 | - root `package.json` scripts |
| 70 | - `desktop/scripts/smoke.mjs` for packaged-smoke expectations |
| 71 | - `scripts/prod-desktop.mjs` only when the failure is prod-local or installer |
| 72 | related |
| 73 | |
| 74 | When docs and scripts disagree, scripts are the executable truth for the active |
| 75 | diagnosis. Record the mismatch as a docs follow-up if it matters. |
| 76 | |
| 77 | ### 3. Verify the active runtime before repairing |
| 78 | |
| 79 | Check the local server and org list when the API is expected to be running: |
| 80 | |
| 81 | ```bash |
| 82 | curl -sS http://127.0.0.1:3100/api/health |
| 83 | curl -sS http://127.0.0.1:3100/api/orgs |
| 84 | ``` |
| 85 | |
| 86 | If the Desktop shell is pointed at another base URL, use that URL instead. |
| 87 | |
| 88 | Common causes to distinguish: |
| 89 | |
| 90 | - no server process is running |
| 91 | - wrong port or stale process owns the port |
| 92 | - embedded Postgres failed to initialize |
| 93 | - dev server is up but Electron did not launch |
| 94 | - Electron launched but cannot reach the server |
| 95 | - API/server is healthy, but Desktop launch is blocked because `@rudderhq/ui` |
| 96 | build/typecheck fails on dirty WIP, incomplete fixtures, or an untracked |
| 97 | companion feature file |
| 98 | - Desktop profile or instance id points to unexpected data |
| 99 | - update metadata resolves but asset download/checksum/install fails |
| 100 | - update helper or CLI child process writes progress after its parent pipe is |
| 101 | closed, causing `EPIPE`, `ERR_STREAM_DESTROYED`, `broken pipe`, or an Electron |
| 102 | main-process error dialog during restart |
| 103 | - packaged smoke differs from dev-shell behavior |
| 104 | |
| 105 | ### 4. Repair narrowly |
| 106 | |
| 107 | Prefer the smallest repair that matches the cause: |
| 108 | |
| 109 | - stop only the repo-local stale process when it blocks the port |
| 110 | - reinstall dependencies only when package state or lockfile evidence points |
| 111 | there |
| 112 | - fix script/config code when the failure is reproducible from a clean command |
| 113 | - for dirty-WIP compile failures, build a changed-file ownership packet before |
| 114 | editing: failing path, related untracked files, likely source session or |
| 115 | feature group, and whether a narrow fixture repair would leave a companion |
| 116 | feature half-committed |
| 117 | - reset `~/.rudder/instances/dev` only when the user accepts data loss or the |
| 118 | instance is disposable and the task explicitly targets dev state |
| 119 | - keep release publishing untouched until local Desktop state is green |
| 120 | |
| 121 | Do not delete `~/.rudder`, change npm auth, move GitHub dist-tags, or install a |
| 122 | new app globally as a "dev recovery" shortcut. |
| 123 | |
| 124 | If the compile blocker belongs to a larger unrelated feature already |
People who liked this also viewed
6 picksType
- paperclip-create-agentCreate new agents in Paperclip with governance-aware hiring. Use when you need to inspect adapter configuration options, compare existing agent configs, draft a new agent prompt/config, and submit a hSkillsJul 2026
- subagent-driven-developmentUse when executing implementation plans with independent tasks in the current sessionSkillsJul 2026
- dispatching-parallel-agentsUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesSkillsJul 2026
- browser-act-skill-forgeForges reusable Skill packages (SKILL.md + scripts) from website exploration via browser-act — no re-exploration later. Use when: user wants a reusable Skill for any website, needs to understand a sitSkillsJul 2026
- wizardGenerate an interactive bash wizard that walks a human through a manual procedure — third-party setup, a one-off migration, an A→B state transition — opening URLs, capturing values, confirming each stSkillsJul 2026
- wonda-cliUsing the Wonda CLI to generate images, videos, music, and audio from the terminal — plus LinkedIn, Reddit, and X/Twitter research and automationSkillsJul 2026
