grill-with-docs

Interviews operators to sharpen goals and writes brainstorms, ADRs, and glossary docs.

3|1|Updated Apr 15, 2026
One-click install
npx skills add https://github.com/burningportra/agent-flywheel-plugin --skill grill-with-docs-burningportra
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: grill-with-docs
Source: https://github.com/burningportra/agent-flywheel-plugin/tree/main/skills/grill-with-docs
Command: npx skills add https://github.com/burningportra/agent-flywheel-plugin --skill grill-with-docs-burningportra

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Vague or contested goals leak into plans and code, causing rework and re-litigated decisions. This Skill runs a structured adversarial interview that pins down scope, non-goals, and success criteria, then persists the answers as durable documentation before any planning begins. ## Core Features & Use Cases - Structured goal interview: Runs 4-8 rounds of AskUserQuestion prompts covering problem, scope floor, ambition ceiling, non-goals, success criteria, constraints, and kill criteria. - Durable documentation: Writes a brainstorm artifact with required headings, load-bearing ADRs in docs/adr/, and glossary entries for new domain terms. - Resume and handoff: Detects prior brainstorm artifacts to reuse or delta-grill, then emits an enriched goal string for the flywheel planner. - Use Case: Before starting a multi-agent coding cycle on an ambiguous feature, run the grill to produce an approved Goal Card and brainstorm file that the planner consumes directly, skipping redundant framing phases. ## Quick Start Ask the agent to grill the goal "add resumable checkpoints to the pipeline" with docs before any planning begins.

Frequently Asked Questions about grill-with-docs

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I refine a vague coding goal before planning?

Run a structured goal interview that asks one decision per turn about problem, scope floor, ambition ceiling, non-goals, and falsifiable success criteria. The answers are synthesized into a Goal Card for approval, then written to a brainstorm document the planner reads first.

What is the difference between a brainstorm doc and an ADR?

A brainstorm artifact captures the full framing of one goal: scope floor, ceiling, non-goals, and success criteria. An ADR records a single load-bearing decision with context, alternatives, and consequences, and is only written when future work might re-suggest the rejected option.

When should I skip goal framing and go straight to planning?

Skip framing for concrete bugfixes, one-file chores, or goals that already state scope, constraints, and success criteria explicitly. Full product design specs and scored idea comparisons are also out of scope and belong to dedicated brainstorming or idea-selection tools.

Can I resume a previous goal interview instead of starting over?

Yes. The process checks for an existing brainstorm matching the goal slug and offers to reuse it as-is, grill only the missing or contested deltas, or start fresh. Reusing skips the interview and jumps straight to handoff.

Why does the interview stop before 8 questions?

The interview stops early when the last two answers no longer change the scope floor, non-goals, or success criteria, or when the operator confirms the framing is solid. This prevents redundant questioning once the goal is stable.