/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

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.

Step 4: Present findings and ask how to proceed

Write a short summary for the user covering:

• **What the problem is** (1-2 sentences)
• **What you found** (root cause or shape of the work, with specific file:line references)
• **Recommended strategy** (the fix or approach you'd take)
• **Why you classified it as simple or complex**

AskUserQuestion with:
- question: "How would you like to proceed?"
- options:
  - "Apply the fix now"   - label: "Fix it"
  - "Run /design first"   - label: "Design it"
  - "Just investigate, don't change anything yet" - label: "Stop here"

If the user picks "Stop here", stop. The investigation summary is the deliverable.

Step 2: Gather evidence

Then use the `AskUserQuestion` tool to ask how to proceed.

For complex work

AskUserQuestion with:
- question: "This looks like it needs a design doc. How would you like to proceed?"
- options:
  - "Run /design to build an implementation plan" - label: "Design it"
  - "Try a smaller scoped fix anyway"             - label: "Narrow scope"
  - "Just investigate, don't change anything yet" - label: "Stop here"

If the user picks "Design it", invoke the `/design` command yourself immediately, passing along the relevant context (problem statement, constraints, open questions, areas of the codebase involved). Do NOT just summarize bullet points and ask the user to invoke `/design` themselves.

If the user picks "Narrow scope", suggest a minimal first step that makes progress without locking in architectural decisions, then ask again whether to apply it.

Output Format

Present findings as a compact report. Do not pad it.

## Problem
[1-2 sentences]

## What I found
[Root cause for bugs, or shape of the work for tasks. Reference specific file:line locations.]

## Recommended strategy
[Your suggested fix or approach. Be concrete.]

## Complexity: