Investigate

Investigate workflow

Perform root cause analysis on a development issue. Use $ARGUMENTS as the error message, problem description, or context if provided (e.g., /investigate Failed to load hooks from hooks.json: expected record, received undefined).

Phase 1: Gather Context

The goal is to understand the problem deeply before jumping to conclusions. Shallow investigation leads to wrong fixes.

1. Parse the input. Extract from $ARGUMENTS or the conversation:

   • Error messages, codes, and stack traces
   • Which command or operation triggered it
   • File paths mentioned in the error
   • Any context the user provided about what they were doing

2. Read the relevant files. Start with files directly mentioned in the error, then fan out:

   • The file(s) where the error originates
   • Config files that govern the failing system (e.g., plugin.json, settings.json, pyproject.toml)
   • Related files that might define the expected schema or format
   • Recent git changes if the error is a regression (git log --oneline -10, git diff HEAD~3)

3. Research the expected behavior. This is the critical step most debugging skips — understanding what should happen before diagnosing what went wrong:

   • Read documentation, schemas, or source code that defines the correct format/behavior
   • Check for examples of the correct pattern elsewhere in the project or in reference implementations
   • If the error involves a third-party tool or framework, use available resources (docs, existing working configs in the project) to understand the contract

4. If the problem is unclear, ask. Use the AskUserQuestion tool to narrow down before proceeding — but only when genuinely ambiguous. Don't ask about things you can determine by reading code.

   • "When did this start happening?" / "Did it work before?"
   • "Which command produces this error?"
   • "Are there other symptoms or related errors?"

Phase 2: Analyze Root Cause(s)

Think through the problem systematically. Most errors have a single root cause, but some have contributing factors worth surfacing.

1. Identify the root cause. Trace from the symptom back to the origin:

   • What does the error message literally say? Parse it carefully — error messages are precise.
   • What code path or validation produces this specific error?
   • What is the gap between the current state and the expected state?

2. Explain the "why" chain. The user wants to understand, not just fix. Walk through the causal chain:

   • What happened → Why it happened → Why that's wrong → What the system expected instead
   • Use specific references: file paths, line numbers, field names, schema expectations

3. Check for related issues. While investigating the primary problem, note:

   • Other instances of the same pattern that might also be broken
   • Contributing factors that made the issue harder to spot (e.g., inconsistent formats across files)
   • Whether this is a symptom of a deeper structural problem

Phase 3: Present Findings and Options

Deliver the analysis clearly, then offer resolution paths. The user decides what to do.

1. Present the root cause analysis. Structure it as:

   • What's happening: One-sentence summary of the symptom
   • Why it's happening: The root cause with evidence (file paths, expected vs. actual values, relevant code/config)
   • Impact: What's affected and what still works

2. Present resolution options. Use the AskUserQuestion tool with concrete options. Each option should be a distinct approach, not variations of the same fix. Include:

   • The recommended fix (mark with "Recommended")
   • Alternative approaches if they exist, with tradeoffs
   • A "do nothing" or "investigate further" option when appropriate

   Design the options so the user can make an informed choice without needing to understand every detail. The description for each option should explain what changes and what the tradeoff is.

3. Apply the chosen fix. After the user selects an option:

   • Make the changes
   • Verify the fix resolves the original error (re-run the failing command if possible, or validate the corrected file structure)
   • Note any follow-up actions the user should take (e.g., "restart the dev server", "re-install the plugin", "clear the cache")

Guidelines

• Read before guessing. Most root causes become obvious once you read the right file — the hard part is knowing which file to read.
• Trace errors precisely. If an error says "expected record at path ['hooks']", look at exactly that path in the data structure. Don't paraphrase the error — parse it.
• Show your evidence. When explaining a root cause, point to the specific file, line, and value that's wrong, alongside what the system expected. The user should be able to verify your analysis independently.
• Don't conflate symptoms. If the user reports multiple errors, determine whether they share a root cause or are independent. Investigate the most upstream cause first — downstream errors often resolve automatically.
• Scope to this project. This skill handles development issues in the llm-wiki project: build/config errors, test failures, plugin problems, script issues, dependency conflicts. For wiki content issues (broken links, missing pages, content quality), suggest /lint instead.
• One investigation at a time. If the user dumps multiple unrelated errors, pick the most impactful one and address it. Mention the others and offer to investigate them next.