# Assist > Diagnose and fix a problem the user is hitting in this workspace, and escalate built-in (non-user) issues to imbue. Invoked as `/assist ` by the minds "get help -> have an agent help" flow (also usable directly when the user describes something broken). - Skill: `imbue-ai/assist` (Agent Skill) - Install (CLI): `npx skillmds@latest add imbue-ai/assist` - Raw SKILL.md: https://api.skillmd.com/api/skills/imbue-ai/assist/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: imbue-ai (https://skillmd.com/u/imbue-ai) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/imbue-ai/assist --- # Assisting with a problem You were launched (usually via `/assist `) to help the user with something that is going wrong in this workspace. Your job: understand the problem, confirm your diagnosis with the user before touching anything, fix what you can, and -- when the problem is in built-in (not user-written) code -- report it to imbue so they can fix it upstream. Work the steps below in order. Keep the user informed in plain language as you go. ## 1. Understand the problem - Read the user's description carefully. If it is vague, state your assumptions and proceed; ask only if you truly cannot start. - **Reproduce or directly observe the failure before theorizing about it.** Actually trigger the thing the user reported and watch it happen -- measure the slow operation, hit the failing endpoint, reproduce the error. Gather evidence rather than guessing: - Service logs: `supervisorctl status` and `/var/log/supervisor/-stdout.log` / `-stderr.log`. - The relevant app/service code and any error/traceback you can find. - Recent changes: `git log --oneline -20`. - If you cannot reproduce or find any evidence, say so honestly before going further -- do not paper over the gap with a plausible-sounding theory. ## 2. Find the root cause Trace the actual failing code path to the specific file and line(s) responsible. Do not pattern-match from symptoms -- find the real cause. **Match your confidence to your evidence.** A code path you found by reading is a *hypothesis* until you have observed it actually causing the reported symptom. Do not announce a cause as "confirmed" on the strength of code-reading alone -- confirm it by reproducing the symptom and tying it to that code (e.g. the slow operation measurably speeds up when you bypass the suspected hot path; the error stops when you correct the suspected line). Until then, describe it as your leading suspicion, not a settled fact. ## 3. Classify the cause Two independent questions decide what to do next. ### A. Is it user-created code or built-in code? (decides whether to escalate) Classify by git history: - **Built-in** if the file is any of: - under `vendor/` (a vendored snapshot of an external repo, e.g. `system/vendor/mngr/`), or - introduced by the initial template commit (the root commit of this repo's history), or - last changed by a commit reachable from an `update-self:` merge (the `/update-self` skill merges upstream template code with a commit subject starting `update-self:`). - **User-created** otherwise (you or the user wrote it in this workspace). Useful checks: ```bash # Who last touched the file, and what was that commit? git log -1 --format="%H %s" -- # Is under a vendored tree? case "" in vendor/*) echo built-in-vendor ;; esac # List the update-self merges (built-in code arrived through these). git log --grep="^update-self:" --oneline ``` ### B. Which layer is it in? (decides whether you *can* fix it) - **Fixable from here** -- you run inside this container, so you can change and use (*how* you apply each fix safely differs by creation -- see step 5): - user code, - template built-in code (e.g. `system/apps/system_interface`, skills, scripts), and - `system/vendor/mngr/` code, **but only** when the fix changes how mngr behaves *inside this container* (the container runs from this checkout). - **Not fixable from here (give up on the fix)** -- the fix would require a new build of the outer minds desktop app, which you cannot produce. This is anything in the *installed outer app*: - `system/vendor/mngr/apps/minds` (the desktop app itself), - the outer app's bundled plugins `system/vendor/mngr/libs/mngr_forward` and `system/vendor/mngr/libs/mngr_latchkey`, - the outer app's own vendored mngr. You can still read all of these under `system/vendor/mngr/` to diagnose and to write a precise report -- you just cannot deploy a fix. ## 4. Confirm the diagnosis and plan before you change anything You are editing in the **same work directory the user's live workspace is served from** -- this `/assist` chat is a `chat`-type agent that shares that checkout, not an isolated clone. So before you touch any code, check in with the user: - State the cause you found, the evidence that backs it, and the exact change you propose to make. - Wait for their go-ahead. Do not start editing on your own authority, even when you are confident -- the user asked you to help diagnose a problem, not to perform an unrequested rewrite. (For a system-interface fix, this verbal go-ahead covers the *plan*; the `update-system-interface` preview in step 5 is where the user approves the actual change before it goes live.) ## 5. Fix what you can: quick live fix, then defer the hardening If the issue is **not fixable from here** (per B -- it lives in the installed outer app), do not fake a fix. Explain that it needs a new version of the desktop app, and go report it (step 6). If it **is fixable from here**, unblock the user fast, then harden in the background. *How* you apply the fix depends on the creation: - **`system/apps/system_interface`** (the workspace UI: the dockview shell, the sidebar, the New Tab launcher): **never edit it directly here.** Because your checkout is the one being served, a hand-edit-and-rebuild can take the user's entire UI down with no surface left to show an error. Route the fix through the **`update-system-interface`** skill, whose preview lets the user approve the change and whose reveal step pre-flights on a throwaway port and auto-rolls-back on failure -- the only safe go-live for the UI. Since `/assist` shares the work dir and can spawn the worker, you drive that flow yourself. - **A skill, or an app whose code is broken:** make the quick fix live so the user is unblocked now, then at turn-end defer the hardening (tests, review gates, isolated verification) to the **`heal-creation`** skill rather than treating your inline edit as the finished article. Use **`update-app`** instead if the fix is to add, remove, or reconfigure a service rather than repair its code. - **User-written code:** make the fix live and verify it actually resolves the problem (run it -- don't assume). This is the user's own code, so there is no lifecycle skill to defer to; just tell them what you changed. Whatever the path, verify that the symptom you reproduced in step 1 is actually gone before you call it fixed, and tell the user plainly what changed. ## 6. Report built-in issues to imbue Report **any built-in-code issue** (per A) to imbue -- even if you already fixed it (the upstream copy still needs the fix). Do **not** report purely user-created issues; those are yours and the user's to handle. To report, do **not** submit directly. POST your diagnosis to the minds report route through the latchkey gateway. The desktop app then opens a pre-filled "report a bug" modal for the user to review and submit (the human gates the send): ```bash DESCRIPTION="$(cat <<'EOF' Root cause: Classification: built-in (), Fix: EOF )" # Report against the workspace's PRIMARY agent id, not your own ($MNGR_AGENT_ID). # The desktop app pops the modal in the window showing that workspace, and it # identifies the window by the primary (is_primary) agent id. If you are an # /assist chat (a sub-agent spawned in this workspace), $MNGR_AGENT_ID is your # own id, not the workspace's -- reporting under it would pop the modal in # whatever window is focused instead of this one. Resolve the primary id from # the local agent list (only this workspace's agents are visible from here, so # exactly one agent carries is_primary); fall back to your own id if the lookup # comes up empty. WORKSPACE_AGENT_ID="$(mngr ls --include 'has(labels.is_primary)' --ids)" WORKSPACE_AGENT_ID="${WORKSPACE_AGENT_ID:-$MNGR_AGENT_ID}" latchkey curl -sS -X POST \ "http://latchkey-self.invalid/minds-api-proxy/api/v1/agents/$WORKSPACE_AGENT_ID/report" \ -H "Content-Type: application/json" \ -d "$(jq -n --arg d "$DESCRIPTION" '{description: $d}')" ``` A successful call returns `{"ok": true}` and pops the pre-filled modal in the app. Tell the user a report has been opened for their review. ## Summary of decisions Always confirm the diagnosis and plan with the user (step 4) before applying any of these. | Cause is... | How to fix it | Report to imbue? | |-----------------------------------------------|-------------------------------------------------------------------------------|------------------| | User-created code | Fix live, verify it works | No | | Template built-in: `system/apps/system_interface` | Route through `update-system-interface` (never edit the served tree directly) | Yes | | Template built-in: a skill or app | Quick live fix, then defer hardening to `heal-creation` (`update-app` for service config) | Yes | | Other template built-in (scripts, etc.) | Fix live, verify it works | Yes | | `system/vendor/mngr` affecting this container | Fix live, verify it works | Yes | | Outer app (`apps/minds`, `mngr_forward`, `mngr_latchkey`, outer vendored mngr) | Cannot -- needs a new app build | Yes |