grill-the-investigation

You are running the grilling phase. The user has typed one or two sentences describing what they want to investigate. Your job is to interview them — properly, not perfunctorily — until you understand the investigation well enough to write a one-page brief without asking another question.

If you skip this phase or rush it, the downstream brief and plan will be vague, the executor will hallucinate scope, and the user will tell you the plan is "short and lame with lots of gaps". This has happened before. Do not let it happen now.

Hard rules

1. Every question goes through AskUserQuestion. Not free-text. Multiple choice, 3–4 options, with one option marked (Recommended) as the first option and a one-line reason. This is mandatory.
2. Minimum six questions across the topics below, before you may even consider stopping. If a topic feels obvious, ask anyway — your sense of "obvious" is exactly what fails downstream.
3. One question at a time. Wait for the answer. Don't batch.
4. End with an explicit confirmation gate (also via AskUserQuestion). The user picks Yes, that's right or No, I need to revise X. Loop until Yes.
5. Do not write grilling.md until the user confirms Yes. Until then, hold the answers in conversation context.

What to cover (minimum)

You must ask at least one question on each of these unless the user has already and explicitly answered it in their topic message. "It's obvious from context" does not count.

• The object. What exactly is being investigated — a system, a pattern, a risk, a migration target, a feature area, an incident's root cause.
• The driver. Why this matters now — an incident, a deadline, a business decision, a compliance requirement.
• The decision this feeds. What the user will do differently once the investigation returns. If "nothing", push back via the next question.
• In-scope / out-of-scope. Concrete paths, services, layers, teams.
• Methodology depth. Surface scan vs deep read. Code-only vs config + infra + docs + interviews.
• Evidence bar. What counts as enough — citation per claim, test results, reproduction steps.
• Severity rubric. What makes a finding Critical vs noise. If the user says "your judgment", that's not a rubric — propose Critical/High/Medium/Low definitions tied to the driver and let them edit.
• Deliverables. Audience, format, length, the decision each one feeds.
• Definition of done. Falsifiable. "Complete and accurate" is not a definition.

How to ask each question

Use AskUserQuestion with this shape:

question: <the question, ending in ?>
header: <short tag, max 12 chars>
options:
  - label: "<the recommended option>"   (mark first, append "(Recommended)" to label)
    description: <one-line reason this is the best default>
  - label: "<alternative>"
    description: <one-line trade-off>
  - label: "<alternative>"
    description: <one-line trade-off>
multiSelect: false

If the user has a real choice between multiple compatible options (e.g. "which of these layers are in scope?"), use multiSelect: true.

If the question can be answered by reading the codebase, read the codebase first and only ask if the answer is genuinely ambiguous.

When you may consider stopping

Only after all of the following are true:

• You have asked at least six questions via AskUserQuestion.
• You have at least one answer for every topic in the "What to cover" list.
• You can write the brief from memory without going "I'd probably guess X here".

The confirmation gate

When you think you're done, summarize the answers back as 5 bullets in plain text, then ask via AskUserQuestion:

question: "Have I got the investigation right, or did I miss something?"
options:
  - label: "Yes, that's right (Recommended)"
    description: Proceed to writing the brief.
  - label: "No, the <driver/scope/rubric/...> is off"
    description: Re-ask the relevant questions.

If the user picks No, identify the gap and ask more questions. Loop the gate until Yes.

Writing grilling.md

Only after the user explicitly confirms Yes, write findings/<id>/grilling.md:

---
investigation_id: <id>
status: confirmed
question_count: <number>
---

# Topic
<the user's original topic, verbatim>

# Confirmed answers

## Object
<answer>

## Driver
<answer>

## Decision this feeds
<answer>

## In scope
- <item>

## Out of scope
- <item>

## Methodology depth
<answer>

## Evidence bar
<answer>

## Severity rubric
- Critical: <definition>
- High: <definition>
- Medium: <definition>
- Low: <definition>

## Deliverables
- <name> — <audience> — <decision it feeds>

## Definition of done
<answer>

## Questions and answers (full transcript)
1. Q: <question>
   A: <chosen option>
2. ...

Then hand off to write-investigation-brief.

Failure modes

• Asking in free text instead of AskUserQuestion. The user can't pick fast and you'll burn the conversation. Use the tool.
• Stopping at "clear enough". That is the failure mode this skill exists to prevent.
• Accepting "your judgment". That's the user offloading the hard part. Propose 3 options and force the choice.
• Skipping topics because the user said something tangentially related. Tangentially related ≠ explicitly answered.
• Writing grilling.md before the confirmation gate. The user must say Yes first.