# Doctor > Diagnose Muse Code product/runtime issues from installed binary evidence. Use ONLY when the user explicitly invokes the doctor skill, asks to debug/troubleshoot Muse Code itself, asks what happened earlier in the current Muse Code session, or explicitly selects an earlier Muse Code session. Do NOT use for ordinary repository code failures or history, benchmark tasks, implementation debugging, build/test hangs, or third-party project issues. - Skill: `shunkakinoki/doctor` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add shunkakinoki/doctor` - Raw SKILL.md: https://api.skillmd.com/api/skills/shunkakinoki/doctor/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: shunkakinoki (https://skillmd.com/u/shunkakinoki) - Updated: 2026-09-10 - Page: https://skillmd.com/skills/shunkakinoki/doctor --- # Diagnose Diagnose Muse Code as an installed product. Use this skill only when the user explicitly invokes `doctor` or clearly asks to debug/troubleshoot Muse Code itself from binary/runtime evidence. Assume the user has the binary, not the source tree. Help them understand how the app works, collect the smallest safe evidence set, identify the likely failing layer, and give the next safe action. ## Scope - Use this skill ONLY when the user explicitly invokes `doctor`, asks to use the doctor skill, or clearly asks to debug/troubleshoot broken Muse Code product behavior: app, CLI, TUI, desktop, crash, provider/model, settings, auth, trust, skills, plugins, MCP, session, resume, export, trace, approvals, sandbox, update, or unexpected output. - Use this skill when the user asks how Muse Code itself works, where Muse Code stores state, what a Muse Code log/session/trace means, or how to collect a Muse Code support bundle. - Use this skill when the user asks what happened earlier in the current Muse Code session or explicitly selects an earlier Muse Code session for evidence. This does not include ordinary repository history or an unspecified third-party agent session. - Do NOT use this skill for ordinary repository engineering: code implementation, third-party project bugs, benchmark/eval tasks, build or test failures, command hangs, toolchain issues, CI failures, or local debugging inside a non-Muse Code codebase. Handle those with the normal engineering workflow unless the evidence points to Muse Code itself. - Treat the user as a product user first, not as a repository engineer. - For pure settings questions or explicitly requested settings edits with no product failure to investigate, use the `manage-settings` skill instead; Diagnose reads settings only as evidence for a failure it is investigating. - Do not create issues, branches, commits, PRs, install/enable/disable skills or plugins, change settings/auth/trust, upload logs, run live-provider/network checks, or edit code unless the user explicitly asks. - Do not print secrets, raw prompts, raw model payloads, auth tokens, API keys, cookies, bearer headers, or full session logs. Prefer redacted exports, key/value presence checks, and concise summaries. - If a surface has no standalone app log, say so and use session logs, crash reports, trace inspection, or export evidence instead of inventing a path. ## Mental Model Explain the relevant product path before asking for logs: - The binary reads settings/auth/trust from the user's config directory and writes sessions, crashes, model catalog cache, and memory under the data directory. - A Muse Code session is the main handle for resume, trace inspection, export, and support. Prefer a session id or session log path over screenshots of terminal output. - Provider/auth failures are often config, environment, model catalog, network, or credential problems. Separate those before blaming the model. - Skills/plugins/MCP are loaded product capabilities. Diagnose discovery, activation, trust, validation, and runtime errors separately. - A trace/export explains what the binary saw and did. It is evidence, not a transcript to paste raw. ## Triage Questions 1. Name the failing surface and exact symptom. 2. Record the command, cwd, session id/path if provided, whether the user wants to inspect or continue that session, approximate time, provider/model if relevant, and whether the issue reproduces. 3. Ask for one missing handle only when it blocks a safe local check. Prefer: exact command, session id/path, time window, and whether they can reproduce. 4. If the user only wants an explanation, explain first and avoid running checks. ## Product Evidence Map Collect the smallest read-only set that explains the issue. Adapt the map to the symptom; do not run every row by default. The config/data roots below are Muse Code's entire local state surface. A config, log, or session file outside them is not Muse Code state — never present one as the product's active configuration, logs, or session evidence. Variables such as `CODEX_HOME` matter only for explicitly requested import/compat evidence and stay attributed to the product that owns them. 1. Build/provenance: `muse --version`; also note `command -v muse` when multiple copies may exist. 2. Config/data roots: `$XDG_CONFIG_HOME/muse` or `$HOME/.config/muse`; `$XDG_DATA_HOME/muse` or `$HOME/.local/share/muse`. 3. Local files: `settings.json`, `auth.json`, and `trust.json`; read settings when relevant, but report auth/trust presence and provider names only. 4. Data dirs: `sessions`, `memory`, `model-catalog`, and `crashes` under the data dir. For crashes, summarize report metadata and file path, not session content. 5. Session evidence: prefer `muse export --redacted --out ` for the latest workspace session, or `muse export --session --redacted --out ` when the user provides a handle. 6. Continuation handles: if the user provides a Muse Code session id and wants to continue that session, point them to `muse resume ` or `muse resume --last` for interactive continuation. Use `muse exec --session-id ""` only on explicit request for headless continuation. Add `--allow-workspace-switch` to the `muse exec --session-id` command only after confirming the session belongs to another workspace; interactive `muse resume` does not take this flag. If an exit, fork, or handoff message printed `muse resume `, treat that command as the canonical handle. 7. Trace evidence: use `muse trace inspect --session-log --render-mode compact`; add `--run-id ` or `--all-runs` for multi-run logs; use `--format json` only when structured analysis is needed. 8. User support bundle: use `/feedback` when available; otherwise prefer a redacted export, trace inspection, crash metadata, and concise reproduction steps. 9. Skills/plugins/MCP: use `muse skills list --enabled-only --json` and safe `muse plugins ... --help` or validation commands when the symptom points there. 10. Environment: check relevant non-secret variables by presence/value only, such as `MUSE_MODEL`, base-url variables with credentials redacted, XDG dirs, `CODEX_HOME` for import/compat issues, and telemetry variables by presence only. ## Use Current Session Evidence First For a question about what happened earlier in the current Muse Code session, use the sibling `scripts/session-evidence.py` helper before export or full trace inspection. After `read_skill` gives the physical Diagnose package path, run: ```bash python3 /scripts/session-evidence.py --session-log --workspace "$PWD" ``` The runtime session-identity context already contains the exact current log path. Do not ask the user for a path already present there, do not guess a latest session, and do not search the session store first. A host may instead provide `MUSE_CURRENT_SESSION_LOG`, in which case the helper can run without a selector. For an explicitly selected earlier Muse Code session, use the exact path or id: ```bash python3 /scripts/session-evidence.py --session-log --workspace "$PWD" python3 /scripts/session-evidence.py --session-id --workspace "$PWD" ``` Both explicit earlier-session forms are current-workspace scoped and fail closed on unknown workspace metadata, a mismatch, or ambiguity. Use `--kind`, `--path`, `--tool`, `--run-id`, or sequence bounds to narrow follow-up evidence. Projected events retain their source stream, and the default bound reserves evidence for both the main session and child sessions so a busy child cannot erase the parent timeline. Always compare durable actions with assistant claims, especially across compaction and child activity. Use a redacted export or compact trace only when this bounded projection is insufficient. Never paste the raw session log into model context. ## Diagnose Live Session Ownership Safely Use this path when resume says a session is already open or the original terminal no longer accepts input: 1. Select the exact session first and run `scripts/session-evidence.py` as above. Bound the output and compare its latest durable activity timestamps; do not start with a store-wide process or file search. 2. Treat `.session.lock` as an inode-backed kernel lease, not a marker file: file existence is not lock ownership, and `flock` protects an open inode. Unlinking a contended pathname can let another process create and lock a new inode while the original writer still owns the old inode. 3. Probe the exact lock read-only with a non-blocking exclusive `flock`. Open it without truncation, report only `acquirable`, `contended`, `missing`, or the read error, then close it immediately. Never resume the session as a probe. 4. Read the lock body's PID only as a hint. A tool sandbox or PID namespace may not see the host process; `ps`/`kill -0` absence inside it cannot prove that the host owner died. Request a host-shell check when that distinction matters. 5. Check the bounded session evidence for prior file mutation involving `.session.lock`, especially `rm`, unlink, replacement, truncation, or recreation. If the path is missing while old activity advances, stop resume attempts and preserve evidence. Never remove, replace, truncate, or recreate `.session.lock` as diagnosis or repair. Never signal the owner from Diagnose. Use only the supported interactive resume picker takeover after the user explicitly chooses it; it remains idle-only and the normal writer lease still decides who may write. Classify the result before recommending an action: | Evidence | Classification | Safe next action | | --- | --- | --- | | Lease is acquirable | No current kernel owner; a leftover pathname is harmless | Retry normal resume; do not clean the file for tidiness | | contended lease with advancing session activity | Live owner and active runtime; terminal attachment may be the failed layer | Preserve the owner; inspect terminal/PTY evidence or exit it normally | | Contended lease with bounded activity idle | Live kernel owner, runtime/terminal health unknown | Use explicit idle takeover from the conflict picker, or collect host-visible stack/trace evidence | | Contended lease but owner-control is unavailable | Live old/incompatible/unreachable owner | Keep fail-closed behavior; exit the old owner normally or collect host evidence | | Lock path was unlinked or replaced while old activity continues | Unsafe prior mutation with possible dual writers | Stop further resume attempts, preserve both inode/session timelines, and escalate; do not recreate the lock | A contended lease proves a live kernel owner, not that its TUI, terminal, provider, or runtime is healthy. Pin the failing layer from activity plus host-visible evidence before proposing a product fix. ## Narrowing Loop Work from evidence: 1. State the most likely layer in one or two concrete sentences. 2. Say why the next check will confirm or reject that hypothesis, then run that one safe local check. 3. Update the hypothesis from the result and continue only while the next check is still relevant and safe. 4. If a live provider, live network, destructive command, or upload is required, state why and get explicit user approval first. 5. If customization or local state is suspected, compare against an isolated temporary XDG config/data profile only after explaining that it will not read or mutate the user's real settings. ## Common Diagnosis Paths - Startup/auth: binary path -> version -> config load -> auth provider present -> model/catalog selection -> first network boundary. - Provider/model: selected provider/model -> base URL with credentials redacted -> auth presence -> model catalog cache -> trace request/error summary. - Session/resume: session id/path -> workspace match -> session log exists -> resume/export/trace command -> whether the user wants inspection or continuation. - Skills/plugins/MCP: list/discovery -> activation/trust -> validation output -> runtime trace or startup diagnostic. - Desktop/TUI: packaged app/binary version -> session id -> UI-visible symptom -> crash/report metadata -> trace/export evidence. Say when source-only tests cannot prove a packaged-app issue. ## Fix Boundary - Settings-only fix: propose the exact change and apply it only after explicit user request; preserve unknown settings fields and verify with a read-back or focused command. - Workspace code fix: switch to the RED-before-GREEN engineering loop only when the user explicitly asks to fix code in the current repo. Reproduce first, edit surgically, rerun the same check, and report incomplete if it still fails. - Product bug report: if the evidence points to Muse Code itself and no local fix is safe, give a concise support bundle with symptom, version, config/data paths, session/crash paths, redacted export/trace evidence, likely cause, and next action. ## Completion Report Include: - Symptom and affected surface. - Product mental model relevant to this failure. - Evidence collected, paths inspected, commands and outcomes. - Redactions applied. - Most likely cause and confidence. - Fix made, proposed, or not made. - Remaining uncertainty and the next safest check.