Grill Me — Human-in-the-Loop Clarification

> ⚠️ THIS SKILL ONLY ASKS QUESTIONS. > It never writes code, creates files, edits text, or implements anything. > When clarification is done, hand off to another skill (e.g. create-prd, > prd-to-tasks) or return control to the user.

Interview the user to resolve ambiguities before executing. Research exhaustively first — the agent MUST do its own homework before asking the human anything. When questions remain, ask exactly one question per turn and wait for the answer before continuing.

Core Principle

> DO YOUR JOB FIRST. Then talk to the human. > Research everything you can on your own. The human's time is precious. > Only interrupt them when you've genuinely hit a wall. > > Don't guess. Don't assume. Don't flood with questions. Research first, > then ask one thing at a time.

⛔ HARD GUARDRAILS (Read Before Acting)

These are not suggestions. Violating any of these is a skill failure.

Guardrail 1: ALWAYS Complete Research Before Asking

You MUST exhaust ALL of these before asking the human a single question:

1. Codebase exploration — Read relevant files, grep for patterns, trace call stacks
2. Project documentation — README, AGENTS.md, CONTRIBUTING.md, docs/
3. Git history — Check commits, blame relevant files, read PR descriptions
4. Online research — Web search for library docs, error messages, best practices
5. Browser actions — Read docs pages, inspect API references, check issue trackers
6. Existing skills — Read other skills in the project for conventions and patterns
7. Configuration files — package.json, tsconfig, eslint, CI configs

Proof of research is REQUIRED. When you ask a question, cite what you checked:

I've researched this:
- Read src/auth/login.ts, src/auth/types.ts, src/auth/middleware.ts
- Checked git log for recent auth changes (3 commits in last week)
- Searched the codebase for "JWT" and "session" patterns
- Read the JWT library docs on npm
- Checked AGENTS.md for project conventions

Here's what I found: [summary of discoveries]

One thing I couldn't determine from research alone: [single question]

Guardrail 2: NEVER Ask What You Can Answer Yourself

Before asking ANY question, answer these:

• Can I find this in a file in the workspace? → READ IT. Don't ask.
• Can I infer this from existing code patterns? → INFER IT. Don't ask.
• Can I look this up online? → WEB SEARCH. Don't ask.
• Can I check the git history? → GIT LOG. Don't ask.
• Can I read the library/framework docs? → BROWSER. Don't ask.

Only after ALL of those are exhausted does a question become valid.

Guardrail 3: Show Your Work

Every question MUST include a Research Log section showing what you did. Omit the research log and the question is invalid. Period.

Guardrail 4: One Question Only

Never ask multiple questions at once. One. Single. Question. Wait for answer. Then research again (new information may answer your other questions). Then ask the next one.

Guardrail 5: Timebox Research, Then Decide

Spend at least 2 minutes researching before asking. Spend at most 10 minutes. If research isn't yielding answers after 10 minutes, it's okay to ask — but you must show what you tried.

When to Use

• The user's request is ambiguous or open to multiple interpretations
• Key constraints are missing (language, framework, target platform, scope)
• The user references something that doesn't exist in the codebase
• Trade-offs exist and the user hasn't expressed a preference
• The request contradicts existing code or conventions

When NOT to Use

• The request is clear, specific, and all parameters are known
• The ambiguity can be resolved by reading files already in the workspace
• The answer is a well-known fact (use web search instead)
• The user explicitly said "just do it" or "use your best judgment"
• You haven't done your research yet — if you haven't exhausted codebase

exploration, git history, and online search, you CANNOT use this skill yet. Do the research first. Then judge if questions remain.

• You intend to implement something. This skill never writes code, creates files,

or edits text. It only asks questions. Use implement-tasks, prd-to-tasks, or direct execution for building.

Process

Step 1: Mandatory Self-Service Research (DO NOT SKIP)

This is not optional. You MUST complete ALL applicable research categories before proceeding to Step 2. If you skip this, you are violating the core promise of this skill.

Before asking the human, exhaust these sources in order:

1A. Codebase Exploration (Always)

bash
# Search for relevant patterns
grep -rn "<keyword>" --include="*.go" --include="*.ts" --include="*.tsx" .
rg "<pattern>" .

# Read relevant files IN FULL (not just skimming)
cat src/<likely-relevant-file>.ts

# Trace call stacks and dependencies
grep -rn "import.*from" src/<area>/ --include="*.ts"

# Find where a symbol is defined and used
grep -rn "functionName\|ClassName\|variableName" --include="*.ts" .

# List the project structure
find . -maxdepth 3 -type d | head -50
ls -la src/

1B. Project Documentation (Always)

bash
# Every project has at least some of these
cat README.md 2>/dev/null
cat AGENTS.md 2>/dev/null
cat CONTRIBUTING.md 2>/dev/null
cat CODEOWNERS 2>/dev/null
ls docs/ 2>/dev/null
cat package.json 2>/dev/null
cat go.mod 2>/dev/null

1C. Git Archaeology (When relevant)

bash
# Recent changes to the area of interest
git log --oneline -20 -- src/<area>/

# Who last touched this file and why
git log --oneline -5 -- src/<specific-file>
git blame src/<specific-file> | head -30

# What changed in a specific commit
git show <commit-hash> --stat

1D. Online Research (Browser & Web Search)

bash
# Search for library documentation
# Use web search for: "<library> docs", "<error message>", "<pattern> best practices"

# Read official docs with browser
# Navigate to library docs, API references, GitHub issues

# Check for existing solutions
# Search: "<problem description> <framework>"
# Search: "<error message> site:github.com"

1E. Existing Skills & Conventions (When in a skills project)

Read other skill files in .agents/skills/ to understand:

• How skills reference each other (metadata.dependencies patterns)
• Common YAML frontmatter conventions
• Script dependency patterns (metadata.scripts)
• Documentation structure and style

Decision Point (After Exhaustive Research)

After completing the research categories above:

• If ALL questions are answered → Exit, hand off to appropriate skill
• If ANY critical ambiguity remains → Go to Step 2 (but cite your research)

Step 2: Identify the Most Critical Unknown

Scan your remaining questions and pick the single most blocking one — the question whose answer has the biggest impact on subsequent decisions. Priority order:

1. Scope questions — What exactly are we building? ("Full auth system or just login?")
2. Constraint questions — What are the hard limits? ("Must it work offline?")
3. Preference questions — Which of these valid options? ("REST or GraphQL?")
4. Detail questions — Specific parameter values ("How many items per page?")

Step 3: Ask ONE Question

Frame it clearly with context and options:

I've reviewed the codebase and found [relevant context].

Before I proceed, one question: [clear, specific question]?

Options:
- A: [option with brief rationale]
- B: [option with brief rationale]
- C: [something else — you tell me]

Step 4: Wait for Answer → Loop

Receive the answer, integrate it into your understanding, then:

• If ambiguities remain → go back to Step 2 (ask the next question)
• If everything is clear → go to Step 5 (exit and hand off)

Step 5: Exit — Hand Off, Don't Build

Once all critical ambiguities are resolved:

1. Summarize the clarified requirements in a structured format
2. Recommend the next skill to use (e.g. create-prd, prd-to-tasks,

implement-tasks) or ask the user what they'd like to do next

1. Stop. Do not write code, create files, or make edits.

Example exit:

Got it. Here's the clarified plan:

- Provider: Itaú PIX API
- Flow: donation form → checkout with QR code → thank-you page
- Architecture: stateless, Cloudflare Workers
- Pages: /contributing (form), /donate (checkout), /thank-you (success)

Ready to turn this into a PRD with `create-prd`. Want me to proceed?

Question Templates

Scope Clarification

I see [existing code/pattern]. For this request, should I:
- A: Extend the existing [component/module]?
- B: Create a new standalone [component/module]?
- C: Replace the existing one entirely?

Constraint Discovery

Before I design this, are there any constraints I should know about?
- Must work with: [existing system/library]?
- Performance targets: [specific numbers]?
- Deadline or priority: [urgent vs nice-to-have]?

Preference Between Valid Options

I can implement this two ways:
- A: [approach] — simpler, but [trade-off]
- B: [approach] — more flexible, but [trade-off]

Which do you prefer?

Anti-Patterns

| Don't | Do Instead | | --------------------------------------- | --------------------------------------------------------- | | Ask 5 questions at once | Ask the most important one, let the answer guide the next | | Ask questions answerable by grep | Search the codebase first | | Ask "What do you want?" with no options | Present concrete options with trade-offs | | Guess and hope it's right | Spend 30 seconds asking vs hours redoing | | Keep asking when 80% clarity is enough | Accept reasonable defaults for low-impact details | | Ask without showing research | Every question MUST include a Research Log | | Skip codebase exploration | Read files, trace patterns, check git BEFORE asking | | Ask before searching the web | Browser and web search are MANDATORY research tools | | Fire questions immediately | Minimum 2 minutes of self-service research first | | Ask about framework/library APIs | Read the official docs with browser BEFORE asking |

Examples

Good: One Question at a Time

User: "Add authentication to the API"

Agent (reads codebase first):

I see you have a Hono API in src/api/ with existing route handlers.
No auth middleware exists yet.

One question: Should I use JWT tokens or session-based auth?
- A: JWT — stateless, simpler to implement, works well with SPA frontends
- B: Sessions — stateful, easier to revoke, requires session store

User: "JWT"

Agent:

Got it. I see src/api/middleware/ is empty. One more: should
authentication be global (all routes) or per-route opt-in?
- A: Global middleware on all /api/* routes
- B: Per-route with an `authRequired()` helper

Good: Resolving Contradictions

User: "Use the same color scheme as the dashboard"

Agent (reads codebase):

I checked src/styles/ and found two color schemes:
- dashboard-legacy.css (last modified 2023)
- dashboard-v2.css (last modified 2024, used by DashboardV2.tsx)

Which one should I use?

Bad: Too Many Questions

❌ "Before I start, I need to know:
1. JWT or sessions?
2. Global or per-route?
3. Which token expiry?
4. Where to store refresh tokens?
5. Should I add rate limiting?"

✅ Ask question 1, get answer, then ask question 2, etc.

Edge Cases

User Says "Just Pick Something"

When the user defers, use sensible defaults and document them:

OK, I'll go with:
- JWT (stateless, standard for SPAs)
- Per-route opt-in (less invasive)
- 24h expiry with refresh rotation

If any of these don't work, just say "change X to Y" and I'll adjust.

User Gives Vague Answers

If the answer doesn't resolve the ambiguity, rephrase:

Sorry, just to make sure I understand — when you say [their answer],
does that mean [specific interpretation A] or [specific interpretation B]?

The Request Is Fundamentally Unclear

If after 2-3 rounds the request still doesn't make sense, reset:

I want to make sure I'm on the right track. Could you describe the
problem you're trying to solve, rather than the solution? What's the
user-facing goal here?

Integration with Other Skills

With mixture-of-experts

Use grill-me to clarify the problem statement before spawning experts:

1. Grill the user to get a clear problem definition
2. Feed that definition to mixture-of-experts for analysis
3. Present MoE synthesis back to user

With create-prd

Clarify scope and constraints via grill-me, then feed the answers into create-prd:

1. Grill user on scope, constraints, and priorities
2. Exit grill-me → invoke create-prd with the clarified requirements
3. Review PRD with user (one more grill-me pass if needed)

With implement-tasks

Use grill-me to resolve ambiguous tasks in tasks.json before delegating. Once ambiguities are resolved, exit grill-me and hand back to the implementation flow.

Best Practices

• Front-load scope questions — Everything else depends on scope
• Present options, not open-ended prompts — Reduces cognitive load on the user
• Show your work — Tell the user what you checked before asking
• Accept "I don't know" — Note it as an assumption and move on
• Timebox — If the user seems stuck, offer to prototype both options
• Keep a mental (or file-based) decision log — Don't re-ask answered questions