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 <file> for the latest workspace session, or muse export --session <id-or-session.jsonl> --redacted --out <file> 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 <session-id> or muse resume --last for interactive continuation. Use muse exec --session-id <session-id> "<follow-up>" 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 <session-id>, treat that command as the canonical handle.
7. Trace evidence: use muse trace inspect --session-log <session.jsonl> --render-mode compact; add --run-id <uuid> 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:

python3 <doctor-skill-dir>/scripts/session-evidence.py --session-log <current-session.jsonl> --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:

python3 <doctor-skill-dir>/scripts/session-evidence.py --session-log <explicit-session.jsonl> --workspace "$PWD"
python3 <doctor-skill-dir>/scripts/session-evidence.py --session-id <explicit-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:

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.