grill-with-docs

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

Ask the questions one at a time, waiting for feedback on each question before continuing.

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

How to ask questions

Dispatch rule (check at runtime):

1. If flt is on PATH AND ~/.flt/ exists, use flt ask human '<json>' via the Bash tool. This persists the Q/A under ~/.flt/qna/ so the mutator/GEPA loop can train on it. The JSON shape is identical to AskUserQuestion's (1 question per call here — see batch sizing below — with 2-4 options, multiSelect, optional preview for single-select). Block on the bash call until the human answers; the command prints the answer JSON to stdout.
2. Otherwise fall back to the native AskUserQuestion tool. Same JSON shape.

Either way, never dump prose with "Q1/Q2/Q3" sections — that's less readable than the interactive picker.

flt ask human payload shape:

{"questions":[
  {"id":"q-3a4f","header":"Auth","question":"Which approach?","multiSelect":false,
   "options":[
     {"label":"OAuth+JWT","description":"Standard but heavier"},
     {"label":"Sessions","description":"Simpler, same-origin only"}
   ]}
]}

The id field is required for flt ask human (random short slug, agent-provided). For native AskUserQuestion the runtime supplies the id implicitly — you don't need to write one.

Batch sizing for this skill: one question per call. The <what-to-do> block above mandates serial questioning so the user's answer can shape the next branch of the design tree. Don't batch multiple questions even when the underlying primitive supports it.

For each question:

• Be specific. Reference actual code, types, and functions you found during exploration — not "how should errors be handled?" but "if cancelOrder is called on an Order with no remaining items, should it throw or no-op?"
• Pre-populate options — faster for the user to pick than to invent from scratch
• If you have a recommendation, make it the first option and label it "(Recommended)"
• Use the preview field on options when mockups/code/configs help visual comparison (single-select only)

Only fall back to prose if the decision genuinely can't be reduced to discrete options.