Use when changing libsync backend services, routers, event wiring, or SDK integration; when adding a new source, WebSocket event, config key, or a new writer of album download_status; when a WS event never reaches the UI, albums stay stuck in queued/downloading after a restart, dedup skips downloads unexpectedly, or pagination total reads 0; or when reviewing a diff that touches mark-downloaded, client hot-reload, dedup DB placement, or the static SPA route.
Use when setting up libsync from a fresh clone; when make deps, poetry install, or npm install fails; when ModuleNotFoundError: No module named 'qobuz' or 'tidal' appears; when docker build fails or bakes unexpected SDK code; when make dev serves a 404 UI or make dev-frontend requests hit the wrong port; when the sdks/qobuz_api_client submodule is empty, dirty, or needs a pin bump; or when local Python/Node/Poetry versions differ from CI and behavior diverges.
Use when merging, opening a PR, or classifying a change in the libsync repo — deciding if a change needs a spec, plan, or CHANGELOG entry; when a required check (backend-tests, frontend-build, docker-publish, ruff) blocks a merge; when someone proposes renaming "streamrip" identifiers, overwriting qobuz_app_id, rewriting the SPA path guard for CodeQL, vendoring/bypassing the SDK submodule, editing design tokens, or basing work on origin/dev.
Use when a libsync setting or credential change does not take effect, STREAMRIP_DB_PATH or STREAMRIP_DOWNLOADS_PATH seems ignored, a Settings toggle silently inverts, downloads land in an unexpected folder layout, auto-sync never fires or fires late, GET or PATCH /api/config returns 500 or unexpected defaults, .streamrip.json sentinels stop being written, or when adding, renaming, or auditing any config key or environment variable.
Use when libsync misbehaves at runtime: downloads 401 while the library loads, a settings toggle acts inverted or ignored, logger.info never prints, ModuleNotFoundError: No module named qobuz/tidal, make lint fails on untouched main, UI 404s while /api answers, a downloaded FLAC is not real FLAC, Tidal capped at AAC 320, scan stuck at 0/? or 409 'Another scan is already running', 'database is locked', albums stuck queued after restart, PKCE 400 'Unknown handle', or grep finds deleted code.
Use when a libsync symptom needs measurement instead of eyeballing - this skill ships runnable read-only scripts to dump the config table with secrets redacted, probe what actually arrives on the live WebSocket, report album download_status states, reconcile .streamrip.json sentinels against the library DB, inspect the per-source dedup DBs behind silently skipped re-downloads, or health-check a fresh checkout; also use when you need visible backend INFO logs via the shipped uvicorn --log-config (the backend configures no logging of its own).
Use when writing or updating any libsync doc — CHANGELOG entries, README, CLAUDE.md, docs/WEB_UI.md, specs/plans under docs/superpowers/, or a new skill; when two docs disagree (e.g. about Tidal auth or endpoints); when a doc references a file that does not exist; when deciding which doc to trust or which doc to update after adding an endpoint or config key; or when asked about the house changelog format, commit-message style, or spec/plan naming convention.
Use when writing anything public about libsync — README or website copy, release notes, feature claims, screenshots, demo videos, blog or social posts; when handling .har captures, tokens, or /api/config output that could leave the machine; when asked about the GPL license, the nathom/streamrip fork lineage, the 2026-04-14 history reroot, or the FUNDING.yml sponsor button; when an external user wants to file an issue or contribute; or when deciding whether a capability may be claimed.