grill-me

Grill Me

Use this vs grill-with-docs: grill-me surfaces assumptions from the conversation and context alone — no documentation fetching. Use grill-with-docs (the doc-grounded variant) when the plan relies on a specific library or external API and every challenge must cite a real doc URL.

Two modes. Default is Design. Switch to Docs by saying "grill me with docs" or when the plan relies on a specific library or external API.

HARD GATE — Do NOT accept a design until every hard decision has been stress-tested. "Seems right" is not a decision. Grilling must identify and resolve tensions before build begins.

Design mode (default)

Interview relentlessly about every aspect of this plan until reaching shared understanding. Walk each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer. Ask one question at a time.

If a question can be answered by exploring the codebase, explore it instead.

Facts vs. Decisions Boundary

Distinguish between facts and decisions:

• Facts — things discoverable by exploring the codebase, reading docs, or checking APIs. Do not ask the user to confirm facts; find them yourself.
• Decisions — choices that require user input (trade-offs, preferences, priorities). Always present options and ask the user to choose.

Never "grill yourself" — if the answer is in the code, go find it. Only ask questions where the user's judgment is needed.

Docs mode

Ground every challenge in real documentation — no assumption about a library's behavior goes unchecked. See REFERENCE.md for the full process.

Short form:

1. List every external library, third-party API, and framework behavior relied upon.
2. Fetch the actual docs for each (WebFetch the official API reference).
3. Challenge each plan assumption against the real docs: correct method signature? right version? deprecated?
4. Report confirmed ✓, corrected ✗ (with the real behavior), and uncertain → spike-prototype.
5. Update the plan for each confirmed discrepancy.

Confirmation Gate

HARD GATE — Do NOT enact the plan or generate specifications until the user explicitly confirms shared understanding. Wait for explicit approval (e.g., "looks good", "confirmed", "proceed") before transitioning to any implementation, spec-writing, or task-slicing step.

---

Docs Mode — Full Process

Triggered by "grill me with docs" or when a plan depends on a specific library or external API.

Why this matters: AI agents hallucinate API methods, argument orders, and behaviors. Every assumption about an external dependency must be validated against the actual docs before code is written.

Step 1 — Identify the dependencies

From the plan or conversation, list:

• Every external library being used
• Every third-party API being called
• Every framework behavior being relied upon

Ask: "Which of these are you most confident about? Which are you less sure of?"

Step 2 — Fetch the relevant docs

For each dependency, fetch the actual documentation:

WebFetch the official docs for [library/API]

Prioritize:

• The API reference for the specific method being used
• The changelog for the version in use (breaking changes)
• Migration guides if upgrading from a previous version
• Known gotchas / FAQ sections

Step 3 — Challenge each assumption

For every assumption in the plan, find the corresponding doc section and ask:

• "Does the real API actually work this way? Show me the doc."
• "Is this method available in the version you're using?"
• "Does this argument order match the actual signature?"
• "Are there rate limits, quotas, or timeout behaviors that affect this design?"
• "Is this marked as deprecated in the current version?"

Ask one question at a time. For each challenge, cite the specific URL and section.

Step 4 — Surface hallucinations

When an assumption doesn't match the docs:

"Your plan uses library.doThing(a, b) but the docs show the signature is doThing(config: {a, b}) with a config object. This will fail at runtime."

Document each discrepancy clearly.

Step 5 — Update the plan

For each confirmed discrepancy, recommend a concrete fix:

• Correct method signature
• Correct argument order
• Alternative approach that matches what the library actually supports
• Whether a spike (spike-prototype) is needed to validate a remaining uncertainty

Step 6 — Sign off

When all major assumptions have been validated against docs, report:

• Which assumptions were confirmed ✓
• Which were corrected ✗ + what the correct approach is
• Which remain uncertain → recommend spike-prototype