quick-elicit

<!-- sage-metadata cost-tier: sonnet activation: auto tags: [elicitation, specification, planning, requirements, framing] inputs: [codebase] outputs: [spec] requires: [] --> # Quick Elicit Guide the human to articulate a high-quality specification through 4 focused rounds of questions. Takes ~3 minutes, not 20. **Core Principle:** The quality of output is determined by the quality of input. The most expensive failure is building the wrong thing correctly. Round 0 challenges the framing BEFORE the other rounds capture requirements. ## When to Use BUILD mode, before planning. When the human describes something they want to build, add, or change — and no specification exists yet. Do NOT use when: - A spec already exists in `.sage/work/` (skip to planning) - The human has provided a detailed written spec (accept it, don't re-elicit) - FIX mode (the bug report IS the spec) - The human says "just do it" (respect their autonomy, note the risk) ## Process ### Pre-Elicit: Infer What You Can Before asking anything, scan the relevant codebase area to understand: - What tech stack is in use? - What patterns exist in the codebase? - What does the area being changed look like? - What conventions are established? If a `codebase-scan` has been run previously, use its output. Otherwise, scan the relevant files directly (read project config, entry points, and the area being changed). Also scan `.sage/docs/` for existing research artifacts (jtbd-*, ux-audit-*, opportunity-*, user-interview-*). If research exists, note the known pain for use in Round 0. This determines WHAT TO ASK. Don't ask about things you can already see. ### Round 0: Framing (30 seconds) **PURPOSE:** Challenge whether the request is framed around the right problem BEFORE committing to a specification direction. Ask ONE question: **"What goes wrong today without this?"** This is not "what does this feature do?" It's "what specific frustration, failure, or friction makes this worth building?" The answer should be a concrete struggling moment, not an abstract category. - Good answer: "Sellers upload dark, cluttered photos and their listings don't sell. They blame the platform." - Thin answer: "Users need to upload photos." (restates the request, not pain) - Acceptable: "There's no way to add images right now." (genuine gap) **If research context exists:** Reference the known pain instead of asking open-ended: "Research identified [pain]. Is that still the driver, or has something changed?" **If the answer restates the feature instead of the pain**, probe once: "Got it — but what's the actual problem that causes? What goes wrong for the user?" Do NOT probe more than once. If the pain remains unclear after one follow-up, note it and proceed. **The challenge:** Based on the pain + codebase scan, surface one or two implicit premises the user is making: ``` Before we lock this in — I notice two assumptions worth checking: 1. [Premise]: [one sentence stating the assumption] → [one sentence describing why it might be wrong] 2. [Premise]: [one sentence stating the assumption] → [one sentence describing why it might be wrong] Does the original framing still feel right, or should we adjust? ``` **What counts as an implicit premise:** - "This needs a new screen" (maybe the existing screen can be extended) - "This is a frontend problem" (maybe it's a data problem) - "This is one feature" (maybe it's three, and only one matters now) - "Users want this" (maybe they want something adjacent) - "This needs to be built" (maybe it can be configured) **What does NOT count** (don't waste time on these): - Technical implementation choices (that's for planning) - Architecture decisions (that's for spec or architect) - Obvious facts about the codebase (already visible from scan) **User responds in one of three ways:** **"Framing is right."** → Proceed to Round 1 with the original request. Note: `Framing: Original request confirmed. Pain: [stated pain].` **"Let's adjust."** → User provides adjusted framing. Round 1 uses the adjusted framing, not the original request. Note: `Framing: Adjusted from [original] to [adjusted]. Pain: [pain].` **"I don't know / let me think."** → Note uncertainty. Proceed with original framing but flag it: `Framing: Original request (low confidence). Pain: unclear. Consider /research or /jtbd before building.` **At Round 0 completion:** Prepend framing decision to `.sage/decisions.md` BEFORE proceeding to Round 1: ``` ### YYYY-MM-DD — Framing: [initiative] [Chose framing]. Pain: [pain]. Challenged: [premise names]. (quick-elicit Round 0) ``` ### Round 0 bypass conditions Round 0 is skipped in exactly these cases: 1. **Lightweight scope** — Task classified as Lightweight. One component, no design decisions. Framing adds no value to "fix the typo." 2. **Spec already exists** — Framing was already considered. 3. **User says "just do it"** — Agent notes: "Skipping framing challenge. Spec inherits original request without challenge." 4. **FIX mode** — The bug report IS the spec. Pain is self-evident. No other bypass conditions. Standard and Comprehensive ALWAYS get Round 0. **Anti-rationalization contract for Round 0 skip:** Do NOT skip Round 0 because: - "The request is clear enough" — clarity of request ≠ correctness of framing - "This is a small change" — Standard classification means framing matters - "The user already explained the pain" — restate and verify, don't assume - "We discussed this in a previous session" — disk is truth, not memory ### Round 1: Intent (30 seconds) Ask TWO questions: 1. **"What should this do when it's working perfectly?"** Get the happy path. What does success look like from the user's perspective? 2. **"Who uses this, and when?"** Get the actor and trigger. This prevents building features nobody uses. Wait for answers. Then draft a 3-5 sentence **intent statement** and show it: ``` INTENT: [feature name] Framing: [original | adjusted | original (low confidence)] Pain: [the struggling moment, from Round 0] When [actor] does [trigger], the system [behavior]. This enables [value/outcome]. ``` Ask: "Does this capture what you mean? Anything to adjust?" **Note:** If Round 0 adjusted the framing, Round 1's questions are asked about the ADJUSTED framing, not the original request. ### Round 2: Boundaries (60 seconds) Ask up to THREE questions, adapting based on what you inferred from the codebase: 1. **"What should this explicitly NOT do?"** Boundaries prevent scope creep and gold-plating. 2. **"What existing code does this touch? Any concerns?"** Skip if the codebase scan already identified the impact area clearly. 3. **"Any security, performance, or compatibility constraints?"** Skip if the change is purely internal with no user-facing impact. Draft **boundary conditions** and show them: ``` BOUNDARIES: - This feature WILL: [list] - This feature WILL NOT: [list] - Constraints: [any non-functional requirements] - Affected areas: [files/modules identified] ``` Ask: "Anything missing or wrong here?" ### Round 3: Verification (30 seconds) Ask ONE question: **"How will we know this works? What would you test manually?"** The answer becomes acceptance criteria. Draft them and show: ``` ACCEPTANCE CRITERIA: 1. [testable criterion] 2. [testable criterion] 3. [testable criterion] ``` Each criterion MUST be testable — not "works well" but "returns 200 OK with user.id in response body." If the human gives vague criteria, make them specific. ### Output: Feature Spec Combine all four rounds into a spec document saved to `.sage/work/<YYYYMMDD>-<slug>/spec.md` using the minimal spec template. The spec includes a `## Framing` section at the top (from Round 0), followed by Intent, Boundaries, and Acceptance Criteria. Show the complete spec. Ask: "Ready to plan implementation, or anything to adjust?" ## Compression Behavior If the user is visibly impatient, compress to 1 round. The compressed version merges pain + intent into one message: "Before we spec this — what's the actual pain this solves? And then: what should it do when working perfectly?" One message, two questions. Infer boundaries and criteria from context. Show the complete spec with a Framing section for validation. **Even compressed, the framing question survives.** Round 0 can be compressed but NEVER eliminated. A compressed Round 0 still produces a Framing section in the spec. ## Rules **MUST (violation = bad spec or lost trust):** - MUST NOT ask more than 8 questions total across all rounds. - MUST NOT ask about things the codebase scan already revealed. - MUST NOT ask technical implementation questions (that's for planning, not spec). - MUST show the drafted output after each round for validation. - MUST make acceptance criteria testable and specific. - MUST execute Round 0 for Standard+ tasks (see bypass conditions). - MUST prepend framing decision to decisions.md before Round 1. - MUST include a non-empty Framing section in spec output. **SHOULD (violation = suboptimal experience):** - SHOULD respect one-word answers — work with what you have, don't interrogate. - SHOULD make a reasonable choice when the human says "you decide," and state it explicitly so they can override if it's wrong. - SHOULD compress to 1 round if the human is visibly impatient. - SHOULD reference existing research context in Round 0 if available. **MAY (context-dependent):** - MAY skip elicitation entirely if the human provides a detailed written spec. - MAY recommend ARCHITECT mode if requirements are genuinely complex. ## Failure Modes - **Human is impatient:** Compress to 1 round — merge pain + intent question, infer boundaries and criteria from context, show complete spec with Framing. - **Human has already thought deeply:** Skip elicitation, help them write their thoughts into the spec template structure, then validate. - **Requirements are genuinely complex:** Recommend switching to ARCHITECT mode for full elicitation with deep-elicit skill. - **Conflicting requirements surface:** Don't resolve them yourself. Present the conflict clearly and ask the human to decide. - **Low-confidence framing:** Include "Consider /research or /jtbd before building" in the Framing section. Surface at the checkpoint: "The pain behind this isn't fully clear. Want to proceed, or run research first?" This is advisory — do NOT block the user from proceeding.