brainstorm

name: brainstorm description: This skill should be used when the user has a vague problem, wants to think through what to investigate before opening a case, says "I'm not sure what's wrong", "help me think about this", "let's figure out what to investigate", or needs collaborative exploration of the problem space before committing to a structured investigation. Produces a case brief that feeds directly into open-case.

Brainstorm — Collaborative Problem Exploration Before Investigation

Help the user transform a vague concern, symptom, or question into a well-scoped case brief through natural dialogue. This is the THINKING phase before the DOING phase.

Why This Exists

open-case expects a reasonably defined problem and goal. But users often arrive with:

• "Something feels off but I can't pinpoint it"
• "This broke and I have no idea where to start"
• "I have a hunch but no evidence yet"
• "Multiple things might be wrong simultaneously"

This skill bridges that gap — structured thinking before structured investigating.

Checklist

Complete these steps in order:

1. Gather context — explore the environment (files, logs, recent changes, error messages)
2. Identify the pain — ask what's wrong, one question at a time
3. Surface assumptions — what does the user already believe? (these become initial hypotheses)
4. Map the problem space — propose 2-3 framings of what might be going on
5. Scope the investigation — agree on boundaries, budget, and success criteria
6. Produce case brief — structured summary ready for open-case
7. User approves brief — only then transition

Process

Phase 1: Context Gathering

Silently explore the environment to build your own understanding:

• Check recent git log, file changes, error logs
• Read relevant files the user mentions
• Look for recent breakage signals

Do NOT dump findings on the user. Use them to ask better questions.

Phase 2: One Question at a Time

Ask clarifying questions sequentially. Each message = ONE question. Prefer structured choices when possible:

Good patterns:

"When did this start? (a) After yesterday's deploy (b) It's been gradual (c) I just noticed it today"

"What's the impact? (a) Blocking production (b) Degraded performance (c) Cosmetic / annoyance (d) Not sure yet"

"Do you suspect a specific area, or is this wide open?"

Bad patterns:

• Multiple questions in one message
• Open-ended questions when multiple-choice would work
• Asking things you could discover yourself from the codebase

Phase 3: Surface Assumptions

People carry implicit theories. Extract them explicitly:

"It sounds like you suspect [X]. How confident are you — gut feeling, or have you seen evidence?"

"You mentioned [Y]. Is that something you know happened, or something you're worried might have happened?"

Every assumption surfaced becomes either:

• An initial hypothesis (if speculative)
• An initial clue (if partially confirmed)
• A constraint (if definitively known)

Phase 4: Propose Problem Framings

Once you have enough signal, propose 2-3 ways to frame the investigation:

I see a few ways to approach this:

1. **Narrow hunt**: Focus on [specific hypothesis]. Fast if correct, dead end if not.
   - Best if: you're fairly confident about the cause
   - Risk: tunnel vision

2. **Differential diagnosis**: Test multiple hypotheses in parallel.
   - Best if: genuinely unclear what's wrong
   - Risk: slower, broader

3. **Symptom trace**: Follow the observable symptoms backward to their source.
   - Best if: the symptoms are clear even if the cause isn't
   - Risk: may get lost in intermediate layers

Include your recommendation and why.

Phase 5: Scope Agreement

Before producing the brief, confirm:

• Goal: What does "solved" look like?
• Budget: How much time/effort is appropriate? (maps to max_actions)
• Boundaries: What's out of scope?
• Check-in frequency: How often should the investigation pause for discussion?

Phase 6: Produce Case Brief

Synthesize everything into a structured brief:

## Case Brief: <title>

**Crime Scene**: <what's wrong, in one paragraph>
**Goal**: <what "solved" means>
**Scope**: <what's in / out>

**Initial Hypotheses**:
1. [Hypothesis] — confidence: [high/medium/low], basis: [why user thinks this]
2. [Hypothesis] — confidence: [high/medium/low], basis: [why]

**Initial Clues**:
- [Known fact relevant to the case]
- [Observed symptom]

**Constraints**:
- [Hard boundary — things we know for certain]
- [Resource limit — time/effort budget]

**Investigation Approach**: [which framing from Phase 4]
**Budget**: [max_actions] actions, checkpoint every [interval]

**Suggested First Move**: [where to start]

Phase 7: Approval and Transition

Present the brief and ask:

"Here's the case brief. Does this capture what we're investigating? Anything to add or change before I open the case?"

On approval:

• Invoke detective:open-case with the brief as structured input
• The brief maps directly to initial fragments:
  • Crime Scene → observation/evidence
  • Goal → observation/anchor (is_goal: true)
  • Hypotheses → hypothesis/clue
  • Clues → observation/clue
  • Constraints → constraint/anchor

Key Principles

• One question per message — don't overwhelm
• Prefer multiple choice — lower cognitive load
• Extract implicit theories — users know more than they think
• Propose, don't prescribe — always offer alternatives with trade-offs
• No premature investigation — thinking is not wasted time
• Respect the user's instinct — if they have a strong hunch, weight it appropriately

Anti-Patterns

Scaling to Complexity

• Trivial problem (user already knows what's wrong): 2-3 questions → brief → done. Total: ~2 minutes.
• Medium problem (user has symptoms, no clear cause): 5-7 questions → framing → brief. Total: ~5 minutes.
• Complex problem (vague, multi-dimensional): Full process, possibly decompose into sub-investigations.

Don't make simple things complicated. If the user says "the deploy broke the login page" — you don't need to explore 3 framings. Confirm scope, produce brief, move on.

Tone

Curious colleague, not interrogator. Think: two detectives at a whiteboard, coffee in hand, sketching theories before hitting the street.