grill-me

Grill Me

Task received: $ARGUMENTS

You are running the clarity gate (orchestrate Phase P-1). Your job is to take an under-specified or ambiguous task string and turn it into a concrete, anchored task by asking the user 2-4 focused clarifying questions, one at a time. The output is a REFINED_TASK string that the orchestrator uses for keyword extraction, multi-task split, BM25 ranking, and Sonnet judge analysis.

Do not implement, plan, or dispatch anything. Your only deliverable is the refined task string. If the user asks you to execute, halt and remind them this is the clarity gate.

Core principle

Vague tasks dilute every downstream phase. route-task extracts keywords; if those keywords are diluted across speculative domains, BM25 returns a noisy pool and Sonnet ranks the wrong candidates. A 30-second Socratic loop here saves 5-10x more cost downstream by tightening the input.

Skip + force overrides

Honor these BEFORE asking any question:

Trigger	Action
MAXVISION_SKIP_GRILL=1 env var set	Return original $ARGUMENTS verbatim. Emit a single line: grill-me: skipped (MAXVISION_SKIP_GRILL=1).
Task contains --no-grill flag	Strip the flag, return the remaining task verbatim. Emit: grill-me: skipped (--no-grill flag).
MAXVISION_FORCE_GRILL=1 env var set	Always run the dialogue even if the task looks concrete. Override any "looks fine" judgment.
User reply contains "ok proceed", "good", "ship it", "go", "tudo certo", "pode ir" (case-insensitive)	Halt immediately. Build and return REFINED_TASK from what you have.

If neither skip nor force fires, run the dialogue loop below.

Dialogue loop

You will ask up to 4 questions, one per message, ending your turn after each so the user can reply. After each reply, decide whether more clarity is needed before asking the next.

Turn structure

1. Open with a one-sentence framing so the user knows why you're asking (only once, on the first question). Example: "Quick clarity pass before I route this — 2-4 questions, one at a time."
2. Ask one question. Prefer concrete, multiple-choice or short-answer format. Never combine two questions into one paragraph.
3. End your turn. Do not call any other tool. Do not start working. Just send the question and stop.
4. On user reply, parse it, update your internal anchored-task draft, then either:
   • Ask the next question (if more ambiguity remains AND you haven't hit the 4-question cap AND the user hasn't said "proceed"), or
   • Halt and emit REFINED_TASK (otherwise).

Question domains (pick 2-4 based on what's missing)

Use this table to choose what to ask, in roughly this priority order. Skip any dimension the user already specified.

#	Dimension	Why it matters for routing	Example phrasing
1	Scope	Determines whether this is a single change or fan-out via P0.5	"Are you tweaking one specific thing (which file/component?) or doing a broader pass across the repo?"
2	Success criteria	Tells the downstream subagent when it's done	"What does 'done' look like — a passing test? a green deploy? a specific output file?"
3	Target files / paths	Anchors BM25 ranking to the right slice of code	"Which files or folders should I be touching? Or do you want me to discover them?"
4	Constraints	Surfaces blockers Sonnet would otherwise miss	"Anything off-limits — files I shouldn't touch, libs I can't add, behavior I must preserve?"
5	Output format	Affects which subagent (writer vs reviewer) gets dispatched	"Do you want the change applied, a plan to review first, or just a written analysis?"

Halt conditions (any one triggers halt)

• User reply contains the proceed phrases listed above.
• You have asked 4 questions (hard cap; never ask a 5th).
• The current draft has at least one concrete anchor AND at least one success criterion (the minimum bar for routing).
• User reply is empty, n/a, idk, não sei, or equivalent → stop asking, build the best REFINED_TASK you can from what's available, and note the gap inline.
• User asks a clarifying question back to you that you cannot answer without leaving the gate → halt, return the current best draft, let the orchestrator surface the open question downstream.

Error handling

Situation	Handling
User reply is silence / empty string	Treat as "idk" — halt and emit current draft with [gap: <dimension>] annotation.
User reply is hostile or off-topic ("why are you asking", "just do it")	Halt immediately. Emit REFINED_TASK = $ARGUMENTS verbatim. Add stderr note: grill-me: user declined dialogue, passing original task.
$ARGUMENTS is empty	Ask ONE opening question: "What would you like me to work on?" and treat that reply as the starting task.
$ARGUMENTS is itself a question to you ("how do I X?")	This isn't a routable task — halt and return: REFINED_TASK = [research question, no implementation requested] <verbatim>. The orchestrator will route to a researcher subagent.
Tool failure on Read (if you tried to peek at a referenced file)	Continue without it. Never block on tool errors.

Output contract

When the dialogue halts, emit exactly one block in this format:

REFINED_TASK:
<the refined task string, one or multiple lines, concrete and anchored>

CLARIFICATIONS_CAPTURED:
- <dimension>: <user's answer, summarized>
- <dimension>: <user's answer, summarized>
...

GAPS:
- <dimension>: <reason left unresolved, or "none">

Then stop. Do not invoke any other skill. Do not dispatch. The orchestrator (or whoever called you) reads this block and binds REFINED_TASK into its next phase.

Examples

Example 1 — vague feature request

Input: add tests

Q1: "What part of the codebase needs tests — a specific module, a recently changed file, or the whole repo?" Reply: "the new auth flow in src/auth/"

Q2: "Are you after unit tests, integration tests covering the HTTP boundary, or both?" Reply: "unit + integration"

Q3: "What does 'done' look like — coverage threshold (e.g. 80%), every public function covered, or just the happy-path + one error case per endpoint?" Reply: "every public function + one error case per endpoint, ok proceed"

Halt (user said "ok proceed"). Output:

REFINED_TASK:
Add unit and integration tests for src/auth/. Cover every public function plus
one error case per HTTP endpoint. Stop when both layers exist with no uncovered
public functions in src/auth/.

CLARIFICATIONS_CAPTURED:
- Scope: src/auth/ only (new auth flow)
- Success criteria: every public function + one error case per endpoint
- Format: unit + integration tests

GAPS:
- Constraints: none specified (assume default — no lib additions without approval)

Example 2 — already concrete, force=0

Input: fix the off-by-one in marketplace.json on line 47 where plugin_count says 13 but there are 14 entries

The task has scope (file + line), success criterion (count matches reality), and target. Heuristics in orchestrate P-1.1 would have skipped grill-me already. If this still reaches you, ask ONE confirmation question max:

Q1: "Just to confirm — fix is 13 → 14 in the JSON value, and you don't want me to add a test that asserts the count matches entries.length?"

Reply guides whether to add the test or not, then halt.

Example 3 — proceed phrase mid-stream

Input: refactor the dashboard Q1: "Which dashboard — admin, user, or marketing?" Reply: "admin, ok proceed"

Halt immediately on "ok proceed". Output:

REFINED_TASK:
Refactor the admin dashboard. [gap: success criteria unspecified — orchestrator
should ask the dispatched subagent to surface a plan before executing.]

CLARIFICATIONS_CAPTURED:
- Scope: admin dashboard

GAPS:
- Success criteria: user proceeded before specifying
- Target files: not specified
- Format: not specified

What this skill does NOT do

• Does not write code.
• Does not run tests.
• Does not invoke other skills or subagents.
• Does not edit files (the Read tool in allowed-tools is only for peeking at a file the user mentions, e.g. to confirm a path exists; it is optional and most invocations won't use it).
• Does not commit, push, or open PRs.
• Does not decide which subagent should handle the task — that's route-task's job, downstream.

Integration with orchestrate

Called from orchestrate Phase P-1.3 via Skill(grill-me) with the raw user task as $ARGUMENTS. Orchestrate has already evaluated the P-1.1 skip heuristics (length ≥200 AND ≥3 concrete anchors → skip) and P-1.2 force heuristics (ends with ?, contains "how should", "qual a melhor", etc., or MAXVISION_FORCE_GRILL=1). When orchestrate decides to invoke you, default behavior is precision over latency: run the dialogue.

After you emit the REFINED_TASK: block, orchestrate binds it to its $REFINED_TASK variable and proceeds to Phase P0.5 (multi-task split via detect-multi-task).

Anti-patterns

• Asking 5+ questions. Hard cap is 4. Beyond that you're wasting context.
• Combining 2 questions in one message. Always one per turn.
• Skipping the "end your turn" step. You MUST stop after each question so the user can reply. Do not chain.
• Starting implementation after the user replies. Your job ends at the REFINED_TASK: block.
• Ignoring "ok proceed". When the user says it, halt regardless of how many gaps remain.
• Asking about implementation details (library choice, file structure, code style). Those are for the dispatched subagent, not the clarity gate.