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, in this order:

1. Summary — A short, plain-English overview at the very top. 2–5 sentences that explain what we're building, why it matters, and the rough approach, written so a teammate who has never seen this codebase understands the gist in 30 seconds. No jargon dumps. This is the most important part for human readability — write it like you're explaining the feature to a smart colleague over coffee, not filling in a form.
2. Problem / objective — What problem this solves and who it's for, in plain language.
3. Current understanding — What you learned from exploring the codebase and related files.
4. Out of scope / non-goals — What we are explicitly NOT doing, and a one-line why for each.
5. Constraints — Technical, product, or time constraints that shape the work.
6. Confirmed decisions — Things I explicitly answered. For each, record both the decision AND the reason it was chosen, so future-me understands the "why" without re-litigating it.
7. Assumptions — Things you defaulted on without asking. Review these with me before execution.
8. Open questions / unknowns — Kept until answered.
9. Acceptance criteria — With concrete input/output examples whenever possible.
10. Affected files, modules, APIs, or data models — When known.
11. Data model / schema changes — When relevant, with a Mermaid diagram (see Diagrams section).
12. Execution phases or priority — When helpful.
13. Effort estimate — Per task or phase using S / M / L.
14. Task checklist — Concrete todo list using Markdown checkboxes ([ ] and [x]).
15. Risks, blockers, and rollback notes — When relevant.
16. Definition of done — Clear and verifiable.

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.

Human-readable writing

The plan must be genuinely easy for a human to read, not just a structured data dump. Follow these rules:

• Lead with the Summary. A person should be able to read only the top of the file and understand what's happening and why.
• Start each section with one plain-English sentence before any bullets, table, or diagram. Set context first, then list details.
• Explain the "why," not just the "what." Every confirmed decision and non-goal should say the reasoning in a few words. "Use Sidekiq for the retry job (already in the stack, no new infra)" beats "Use Sidekiq."
• Write for a competent teammate who hasn't seen the codebase. Assume they're smart but lack your context.
• Prefer short prose where prose reads better; use bullets for lists, not for everything. Don't shatter a simple explanation into ten fragmented bullets.
• Define any necessary jargon inline in plain English the first time it appears.
• Keep it skimmable. Clear headings, short paragraphs, important decisions and next steps easy to find without reading the whole file.
• Every section should earn its place. If a section is empty or trivial, write "None" rather than padding it.

Diagrams (Mermaid)

Add a diagram whenever it makes the plan easier to understand than words alone. Always use Mermaid fenced code blocks (```mermaid) embedded directly in the Markdown so they render in the file. Keep node and edge labels in plain language. Add a diagram only when it clarifies something important — do not add visual clutter.

Use the right diagram for the job:

• Database / data model changes → erDiagram. Whenever the work adds or changes tables, columns, or relationships, include an ER diagram showing the relevant entities, key fields, and how they relate. Show only the tables touched by this work, not the whole schema.
• Process flows, request lifecycles, integrations, branching logic → flowchart. Use when the feature involves a sequence of steps with decisions or branches.
• Multi-actor interactions (client ↔ server ↔ external service, jobs, webhooks) → sequenceDiagram. Use when the order of calls between components matters.
• Status or lifecycle transitions → stateDiagram-v2. Use when an entity moves through states (e.g. draft → submitted → approved → paid).
• Execution phases / rollout timeline → simple flowchart or gantt. Only if phases and dependencies are non-trivial.

Place each diagram next to the section it explains (e.g. the ER diagram under "Data model / schema changes," the flow under the relevant decision). Keep each diagram focused on one idea. If a single diagram is getting crowded, split it.

Example of an embedded data model diagram:

erDiagram
    USER ||--o{ SUBSCRIPTION : has
    SUBSCRIPTION ||--o{ INVOICE : generates
    SUBSCRIPTION {
        bigint id PK
        bigint user_id FK
        string status
        datetime current_period_end
    }

Loading

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.
• Use Mermaid diagrams per the Diagrams section when they materially improve understanding.
• Do not add visual clutter; every table and 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 clarity

Make every question genuinely easy for me to understand and answer. The goal is that I never have to re-read a question or go dig through the code to figure out what you're really asking.

• Give one line of context first. Before the question, briefly say why you're asking and what it affects (e.g. "This decides whether existing users get migrated automatically or have to opt in."). Then ask the question.
• Lead with the real-world effect, not the mechanism. Ask about what the user/system will actually do, then mention the technical detail if needed — not the other way around.
• Phrase the question in everyday language. If a technical term is unavoidable, define it in plain English in the same breath.
• Make each option concrete. For each answer option, add a short "what this means in practice" so I can picture the outcome of choosing it, not just the label.
• Use a tiny example when the choice is abstract. A small before/after, input/output, or "if we pick A, then X; if B, then Y" comparison is worth more than a paragraph of explanation.
• Don't assume I have the code in my head. Include just enough detail from your exploration that I can answer without opening files.
• If a question is complex, shrink it. Break it down to the single smallest decision I actually need to make right now, and park the rest as follow-ups.

Example of a clear question:

🟡 📦 When a payment retry finally fails for good, who should we notify? Why this matters: it decides whether we need a new email template and an admin alert, or just a status change.

1. ✅ Email the customer only — they fix the card themselves (what this means: one new email, no admin work).
2. ⚖️ Email the customer + flag it for an admin (what this means: one email plus a dashboard alert to build).
3. ⚠️ Silent — just mark the subscription past_due (what this means: no notifications, customer may not notice). Recommended: 1

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 the Summary at the top current — rewrite it as understanding evolves so it always reflects the latest shared picture.
• Keep refining the checklist as understanding improves: add tasks, split tasks, remove invalid tasks, reorder tasks, and mark items done when resolved.
• Add or update Mermaid diagrams as data models and flows become clear.
• 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.
• Do a dedicated readability pass: confirm the Summary alone explains the feature, every section opens with a plain-English lead-in, and every confirmed decision states its "why."
• Confirm diagrams are present where they help (especially an ER diagram for any schema change) and that each one renders as valid Mermaid.
• 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.
• Confirm a non-author could read the Summary plus the diagrams and understand the feature without reading the whole file.
• 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.