Step 3: Clarify Features

Phase: spec

Context

You have app_description and matched_template_or_null. Now you need to fill in the details.

What to do

Ask the user simple questions to clarify features. Rules:

  • One question at a time. Wait for the answer before asking the next.
  • Plain language only. Never use words like: database, API, endpoint, schema, RLS, JWT, REST, backend, frontend, authentication, deployment, hosting, server.
  • Yes/no or multiple choice. Don't ask open-ended technical questions.
  • 3-6 questions max. Don't overwhelm the user. Focus on what matters.

Question categories

Users & access

  • "Should people need to sign in to use this, or is it open to anyone with the link?"
  • "Is this for just you, or will other people use it too?"
  • "Should each person see only their own stuff, or can everyone see everything?"

Content & data

  • "What kind of things will people create or save? (e.g., tasks, messages, scores, photos)"
  • "Should there be categories or groups to organize things?"
  • "Do you want people to be able to search or filter?"

Interaction

  • "Should people be able to react, vote, or comment on things?"
  • "Does anything need to update automatically while people are using it, or is refreshing the page okay?"
  • "Is this a game? If so, is it solo, pass-and-play, or multiplayer over the internet?"

Look & feel

  • "Do you have a color scheme in mind, or should I pick something?"
  • "Should it work well on phones, computers, or both?"

Guardrail-targeted questions

If the user's description hints at any of these, ask explicitly to catch impossible features early:

  • "Do you need instant live updates (like a chat), or is it fine if it checks for new stuff every few seconds?" (catches WebSocket requirement)
  • "Should people sign in with Google/Facebook, or is email and password okay?" (catches OAuth requirement)
  • "Should the app send notifications (email, text, push) or just show updates inside the app?" (catches notification requirement)
  • "Do you want a custom URL like myapp.run402.com, or is the default link fine?" (catches subdomain preference — fully custom domains like myapp.com are not supported)
  • "Does anything need to happen behind the scenes that users can't see, or does everything happen in the app itself?" (catches server-side code requirement)

You don't need to ask all of these — only the ones relevant to the user's description. But when in doubt, ask.

Skip questions that are already answered by the app_description or the matched template. If using a template, focus on customizations: "The [template] includes [features]. Is there anything you'd like to add, remove, or change?"

After each answer, check against the capability guardrails. If the user wants something that's not possible, flag it immediately with the plain-language explanation and alternative. Do not move to the next question until the guardrail issue is resolved (user accepts alternative or drops the feature).

Expected output

  • feature_answers — A structured summary of the user's answers. For each question asked, record the answer. Format as key-value pairs: 
    {
  "requires_signin": true,
  "multiplayer": false,
  "content_types": ["tasks", "notes"],
  "needs_search": true,
  "color_scheme": "blue and white",
  "mobile_friendly": true
}

Memory directive