grill-me.md

Interview me about this plan until we reach a shared understanding of exactly what needs to be done. Walk down each branch of the design tree, resolving dependencies between decisions one by one. For each question, provide your recommended answer.

Plan file

Before asking the first question, create or update a Markdown plan file at .plans/<context-based-name>.md. Create the .plans/ directory if it does not exist. Name the file based on the task context using a short, stable, kebab-case filename such as .plans/inbox-search.md or .plans/billing-webhook-retry.md. If the project root is unclear, use the current working directory. Choose the filename once, state it explicitly, and treat that file as the source of truth throughout the conversation.

The plan file must always include:

• A short objective / problem statement
• The current understanding of the work
• Out of scope / non-goals
• Constraints
• Confirmed decisions (things I explicitly answered)
• Assumptions (things you defaulted on without asking — review these with me before execution)
• Open questions / unknowns
• Acceptance criteria with concrete examples when possible
• Likely affected files, modules, APIs, or data models when known
• Task priority or execution phases when helpful
• Rough effort estimate per task or phase using S / M / L
• A concrete todo/task checklist using Markdown checkboxes ([ ] and [x])
• Risks, blockers, and rollback notes when relevant
• A clear definition of done

Do NOT include implementation code in the plan. Describe what to build using file paths, function/module names, and behavior — not line-by-line code. Tiny snippets are fine only when they clarify a data shape or API contract.

Plan quality

• Make the plan readable for both humans and AI
• Prefer clean Markdown structure with clear headings, short sections, bullets, and checklists
• Write in plain language first; keep it easy to skim
• Preserve enough structure and consistency that the AI can keep updating it reliably
• Keep important decisions and next steps easy to find without reading the whole file
• Use tables only when they make tradeoffs or comparisons easier to understand
• Add simple diagrams or charts only when they materially improve understanding
• When visuals help, prefer lightweight Markdown-friendly formats such as Mermaid flowcharts, sequence diagrams, or small ASCII diagrams
• Do not add visual clutter; every diagram should clarify something important

Exploration before questions

Before asking the first question:

1. Briefly explore the codebase and any related files
2. List what you learned in the plan under "Current understanding"
3. Only ask about things you genuinely could not determine yourself

If a question can be answered by reading the codebase, read the codebase instead of asking me.

Skip the obvious

Before asking each question, check: can I answer this with a reasonable default?

• If yes → record it under "Assumptions" in the plan and skip the question
• If no → ask, but only when my answer would meaningfully change the outcome

Question style

• Keep each question as short as possible while still being clear
• Be direct and to the point
• Use simple language and avoid unnecessary jargon
• If a technical term is necessary, explain it briefly in plain English
• When it would help understanding, include a tiny concrete code example or input/output example
• Prefer examples that compare the options being discussed
• Keep your recommended answer short and practical too
• Move through the questions quickly
• Do not linger on low-impact details
• Prioritize the highest-uncertainty or highest-impact decisions first
• Slow down only when a decision materially changes scope, architecture, risk, or implementation effort

Question pacing

• Ask 🔴 high-impact and 🟡 medium-impact questions strictly one at a time
• For 🟢 low-impact questions, you may batch 2–3 at once if they are independent
• If we exceed ~20 questions total, stop and ask whether to continue or finalize with current understanding

Question labels

• Prefix each question with concise emoji labels to make the interview easy to scan
• Use at most 2 emojis per question: optionally 1 for priority and 1 for type
• Priority emojis: 🔴 high impact, 🟡 medium impact, 🟢 low impact
• Type emojis: 🎯 scope, 🧩 product behavior, 🏗️ architecture, 📦 data/API, 🧪 testing, ⚠️ risk/blocker
• Use emojis consistently
• Example: 🔴 🏗️ Should this live in the existing service or a new one?

Question options

• When a question has a small number of realistic paths, provide 2 to 4 short answer options
• Use options only when they help me decide faster; do not add them to every question
• ALWAYS number each option starting from 1 so I can reply with just the number
• Format: number → status emoji → option text
• Status emojis: ✅ recommended / low risk, ⚖️ balanced tradeoff, ⚠️ higher risk or complexity, 🚫 not recommended
• State your recommended option on a "Recommended: N" line right after the options
• Keep each option short and add a one-line explanation only if needed
• Example:
  • 1. ✅ Reuse the existing endpoint
  • 2. ⚖️ Extend the current service
  • 3. ⚠️ Build a new async pipeline
  • Recommended: 1

My reply shortcuts

• A bare number (e.g. 2) → I selected that option
• A number plus text (e.g. 2, but only for admins) → apply the option plus the modification
• ✅ or yes → accept your recommended option
• ? → explain the tradeoffs in more detail before I decide
• show diff → show what changed in the plan since my last answer, instead of restating everything
• enough, ship it, or go → stop asking questions, fill in remaining unknowns with reasonable defaults clearly labeled under "Assumptions", and present the final plan

Push back when needed

If my answer seems inconsistent with an earlier decision, contradicts what you found in the codebase, or looks like it will cause real problems later, push back once before accepting it. After that, defer to my call.

During the interview

• Ask questions one at a time (with the batching exception above)
• After every answer I give, immediately update the plan file
• Keep refining the checklist as understanding improves: add tasks, split tasks, remove invalid tasks, reorder tasks, and mark items done when resolved
• Keep unresolved questions explicitly listed until they are answered
• Every 5 to 7 questions, or after a major topic is resolved, give a short checkpoint summary
• Each checkpoint summary should include the plan file path and say in 5 bullets or fewer: what is now confirmed, what is still unclear, what changed in the plan
• Continue until both of us understand exactly what needs to be done and the plan is specific enough to execute

After the interview is complete

• Review the entire plan file before treating it as final
• Improve clarity and restructure the plan if needed
• Remove duplicate, stale, or contradicted notes
• Rewrite vague checklist items into clear, actionable tasks
• Reorder tasks based on dependencies and execution order
• Separate confirmed decisions, assumptions, open questions, and blockers clearly
• Walk me through the "Assumptions" section explicitly so I can confirm or correct each one
• Do not silently expand scope; if you add inferred work, label it clearly as optional or inferred

Before execution

• Run a final readiness check
• Confirm the plan has no duplicate tasks, no hidden assumptions, and no contradictory notes
• Confirm the acceptance criteria are concrete enough to verify
• Do not move to execution while any 🔴 high-impact unknown remains unresolved unless I explicitly accept that risk

Once the scope is fully clear, present the cleaned final state of the plan file, including its filename and any remaining risks or blockers, and ask for confirmation before execution.