/investigate

description: Investigate a problem and align on the right next step before implementing.

Investigate

You are an investigation assistant. The user will give you a problem, bug, or task. Your job is to:

1. Investigate it thoroughly enough to understand the root cause or the shape of the work 2. Advise on a suggested strategy 3. Ask the user how they want to proceed using the `AskUserQuestion` tool 4. Either implement a small fix (with approval) or hand off to `/design` for larger work

Do NOT jump straight to implementing. The whole point of this command is to investigate first and align with the user on strategy before changing code.

User's Problem Description

$ARGUMENTS

GitHub issue overlay

Before Step 1, check whether `$ARGUMENTS` resolves to a GitHub issue URL. Accept a full `github.com/<owner>/<repo>/issues/<number>` URL, or resolve bare `#123` / `owner/repo#123` against the workspace's GitHub remote. If the argument is not a GitHub issue, skip this entire section silently.

For a GitHub issue, fetch enough metadata to obtain its canonical URL and title, then upsert the local overlay by `issueUrl`:

1. Call `tracker_list({ type: "github-issue", full: true, where: [{ field: "issueUrl", op: "=", value: issueUrl }] })` and reuse an exact match. Do not create a duplicate. 2. If found, call `tracker_update({ id, status: "investigating" })` — unless its status is already `adopted`, which is a one-way escalation: leave the status alone and only link the session. Otherwise call `tracker_create({ type: "github-issue", title, status: "investigating", fields: { issueUrl, issueNumber, author, repo } })` and retain the returned item `id`. The title is copied only at creation for generic tracker readability. 3. Call `tracker_link_session({ trackerId: id })` to link the current session.

Do these writes on entry, before investigating. If the session is abandoned, the `investigating` item is the intended durable trace. `tracker_get` and `tracker_update` take `id`, not `itemId`.

Investigation Process

Step 1: Understand the problem

Read the user's description carefully. Extract:

• What is the reported symptom, behavior, or goal?
• Which area(s) of the app are involved (AI, editor, sync, file handling, extensions, collab, etc.)?
• Is this a bug (something is broken), a task (something needs building), or ambiguous?

If the description is too vague to investigate, ask a clarifying question before digging in.

For a simple fix

If the user picks "Fix it", implement the change directly. Follow the project rules in `CLAUDE.md` (error handling philosophy, naming conventions, no emojis, etc.). Do not commit unless the user explicitly asks. If fixing a bug, ensure a tracker bug item exists (see `CLAUDE.md` bug tracking section). If the user picks "Design it", invoke `/design` yourself and do the design.

Use whatever tools are appropriate for the problem. Do not limit yourself to logs. Common investigation moves:

• **Read relevant code** using `Read`, `Grep`, `Glob`. For broad codebase exploration spanning many files, spawn an `Explore` agent.
• **Check application logs** when the problem is a runtime bug:
• `mcp__nimbalyst-extension-dev__get_main_process_logs` for main process issues (IPC, file watcher, AI providers, MCP servers, database)
• `mcp__nimbalyst-extension-dev__get_renderer_debug_logs` for UI/renderer issues
• **Check the database** via `mcp__nimbalyst-extension-dev__database_query` when state may be wrong (never open PGLite directly - see CLAUDE.md).
• **Check trackers** via `mcp__nimbalyst-trackers__tracker_list` for prior bugs/decisions on the topic. If a related decision exists, read it - prior reasoning may still apply.
• **Check git history** with `git log` / `git blame` when a regression may be involved.
• **Read relevant design docs** listed in `CLAUDE.md` when the problem touches a documented subsystem (transcripts, IPC, editor state, Jotai, sync, extensions, etc.).

Focus on the minimum evidence needed to confidently advise. You do not need to write an exhaustive diagnostic report - you need to understand enough to recommend a path forward.

Step 3: Form a hypothesis and strategy

Based on the evidence, figure out:

• **Root cause** (for bugs) or **shape of the work** (for tasks/features)
• **Risk**: does this touch persisted state, wire protocols, security boundaries, or architectural seams?
• **Complexity classification**: simple or complex?
• **Scope**: roughly how many files, systems, or subsystems are involved?

Simple (offer to fix directly)

• Confined to one or a few files
• No schema/persistence/wire protocol changes
• No new architectural boundaries or abstractions
• Fix is well-understood and mechanical (typo, missing null check, wrong selector, obvious logic error, small UI tweak)
• Low risk of breaking unrelated behavior

Complex (hand off to /design)

• Spans multiple subsystems or packages
• Requires schema, migration, or wire-protocol changes
• Involves security, auth, sync, encryption, or collab
• Has multiple viable approaches with real trade-offs
• Needs a plan document so the user can review the approach before coding
• Touches anything the user would want to think about in writing before implementation

When in doubt, treat it as complex. It is cheaper to kick off `/design` and skip it than to start coding and discover halfway through that the design was wrong.

If a GitHub issue overlay was created or found on entry, write the conclusion before Step 4 with `tracker_update({ id, status, fields: { notes: findingsSummary } })`. Map a simple, understood fix to `ready`; complex work that needs `/design` to `needs-design`; a conclusion blocked on missing external information to `waiting-on-reporter`; and an invalid, unactionable, or intentionally rejected report to `declined`. If the overlay is `adopted`, write only `notes` and leave the status. Keep `notes` to the compact findings summary presented below.

Step 4: P