--- name: marco-souza/grill-me source: https://app.decimal.ai/s/marco-souza-grill-me@1/SKILL.md source_sha256: 36343919c2e8 --- # 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 "" --include="*.go" --include="*.ts" --include="*.tsx" . rg "" . # Read relevant files IN FULL (not just skimming) cat src/.ts # Trace call stacks and dependencies grep -rn "import.*from" src// --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// # Who last touched this file and why git log --oneline -5 -- src/ git blame src/ | head -30 # What changed in a specific commit git show --stat ``` #### 1D. Online Research (Browser & Web Search) ```bash # Search for library documentation # Use web search for: " docs", "", " best practices" # Read official docs with browser # Navigate to library docs, API references, GitHub issues # Check for existing solutions # Search: " " # Search: " 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 3. **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