Askme

Ask me

Contract

Inputs

• The user's task, request, or handed-over material (required).
• Mode selector: exhaustive (default), collaborative, adversarial, batch, interview, scan, or proposal. Auto-detected from invoking phrasing; an explicit mode argument always overrides auto-detection.
• An ask-user tool exposing single-select and multi-select questions (the harness equivalent of AskUserQuestion). Required to fire question batches; if absent, fall back to sequential chat prompts.
• Mode-specific inputs: scan takes an optional text-or-path target; proposal requires the handed-over material; interview requires a stated goal.

Procedure

1. Select mode. Auto-detect from invoking phrasing: help me refine, walk through with me, let's brainstorm, share tips → collaborative; poke holes, stress-test, grill, find weaknesses → adversarial; batch ask me, clarify the design space, multi-fork decisions, unresolved prerequisites → batch; interview me, define requirements, choose between options → interview; the user asks to clarify, what is ambiguous, find gaps in this spec, or an underspecified request → scan; material arriving without a fully formed ask, or an ask thinner than the data suggests → proposal; anything else or no qualifier → exhaustive. An explicit mode argument always wins over auto-detection. Done when: one mode is selected.

2. Mode proposal: read, then propose. Read every piece of the handed-over material end to end before proposing anything. State the intent read from the data in one line grounded in what the data actually shows, sketch the next action briefly, and propose only to confirm: right, wrong, or adjust. If two intents are plausible, propose the likelier and name the other in a clause; one intent per turn. Done when: the one-line proposal, next-step sketch, and confirm/correct/adjust prompt are emitted.

3. Mode scan: restate and pre-scan. Select the target by strict precedence: an explicit argument, else the most recent user request when it reads as a spec or task, else the open conversation context; read it once for the whole run. Restate the read as a single paraphrased instruction, including what it does not ask for, and compare it against the target; a mismatch is the first finding and outranks every other, because a correct answer to a misread request is still wrong. Then resolve every ambiguity that is an environmental or codebase fact by direct lookup (search, read, or a subagent); record each as tier auto with its basis, and never ask the user for something the repo can answer. Done when: the target is read once, the restatement is compared with any mismatch surfaced as the first finding, and every lookup-resolvable ambiguity is tier auto.

4. Mode scan: tier and emit. Classify every remaining finding with exactly one certainty tier: auto (a project convention resolves it; record the resolution and basis, then proceed), gated (a reasonable default exists; surface it as a recommendation that locks unless the user overrides it), manual (evidence cannot settle genuine intent; surface a non-locking recommendation on the least irreversible standard choice, then ask), fyi (worth noting, never blocking; list it, never ask). Enforce MECE before emitting: merge or drop findings that ask the same thing as, or overlap, another finding. Emit the findings report grouped by tier with manual last, then ask only the manual tier using the question shape in step 12. After the user's overrides, re-scan the target once and stop when the re-scan adds no new manual finding; record every settled finding as overridden, answered, or discharged as a non-issue with a one-line reason, and list any settled project-specific term as a CONCEPTS.md candidate (record it; write no files). Done when: the report is emitted, manual questions are fired or none exist, and the re-scan adds no new manual finding.

5. Mode interview: one assumption at a time. State that this is a requirements interview and confirm whether the goal is defining requirements, resolving a decision between options, or both; begin no file change, build, or investigation until the decision record is approved. Ask one focused question that exposes the most fundamental unstated assumption in the stated goal; wait for the response; restate what was confirmed or corrected and add it as a row in the running decision log; after each answer ask "What else is unstated or assumed in this goal?" Stop when the user says nothing remains, explicitly declines, or confirms the record is complete. Present the complete log (each assumption, its resolution, and the final agreed scope or decision; no implementation plan), ask the user to approve, amend, or reject any row, and repeat until approved. Write the approved record to a local file named by the user or defaulting to DECISION-LOG.md in the current working directory. Done when: the user approves the record and it is written.

6. Modes exhaustive, adversarial, and batch: Verbalized Sampling (VS). Sample multiple intent hypotheses; assign each a probability weight on a 0–1 scale; state the falsifier (the specific observation or scenario that would invalidate it) per hypothesis. Expand hypothesis depth as ambiguity, risk, or architectural surface grows; keep it concise when scope is truly narrow. Render the VS block in this format before the first question fire:

1. [Weight: 0.42] hypothesis here
   - Falsifier: [observation or scenario that would invalidate this]

2. [Weight: 0.28] hypothesis here
   - Falsifier: [observation or scenario that would invalidate this]

For batch mode, seed the design-tree roots and initial frontier from the surviving hypotheses. Done when: the weighted hypotheses and falsifiers are presented and, for batch, the roots and frontier are seeded.

7. Mode exhaustive: exploration. Deliberately seek unconventional, underexplored, and edge-case possibilities relating to the user's objective, drawing on context and plausible but non-obvious requirements. Include at least 3 edge cases (at least 5 if architectural); stop expanding once additional cases no longer change decisions. Broaden sampling if no clear leader emerges. Synthesize surviving hypotheses into one consolidated direction before responding. Done when: edge cases are explored and surviving hypotheses are synthesized into one consolidated direction.

8. Mode collaborative. Do not run VS. Two-way tip-sharing dialogue: surface one of the agent's own observations or tips back to the user as a counter-tip per round; let depth emerge through exchange. No scoring, no ranked sample. Stop when the user signals convergence. Done when: the user signals convergence.

9. Mode adversarial: walk the tree one fork at a time. Per fork: state the question, recommend an answer with a one-sentence rationale, wait for the user, and do not proceed on assumed answers. Resolve dependencies parents-first; do not descend into children while a parent is unresolved. Done when: every fork is resolved or a blocking unknown is reported.

10. Mode batch: frontier rounds. Build a design tree where each node is a decision; the frontier is every decision whose prerequisites are already settled, the questions to ask now without guessing at answers not yet heard. Each round, ask the whole frontier as a batch of single-select questions, each with a recommended answer; a question whose answer depends on another open question belongs to a later round, not this one. When the frontier exceeds the per-fire cap, keep the whole frontier in one round: route the four highest-impact questions through the tool (chosen by how many downstream decisions each answer unblocks, ties toward the question whose default is least safe to assume) and put every remaining question in the same message as numbered Markdown **Q<n>: <question title>** followed by the body, choices, and -> Recommended: <answer>; answers from the tool and the Markdown questions settle together in one round-trip. Finding facts is the agent's job, not the user's: when a frontier question needs an environmental fact (filesystem, tools, codebase), dispatch a subagent to find it and never ask the user for something that can be looked up directly; a running exploration is an unsettled prerequisite, so only its downstream questions wait. Recompute the frontier once after each full answer set; do not resample VS unless user answers materially change the survivor set. Done when: the frontier is empty, every branch of the design tree is visited, and the user confirms shared understanding.

11. Escalation (collaborative → adversarial). Promote mid-session when any of these fire: (a) ambiguity cardinality ≥ 2 valid architectural decisions surface from a single user message; (b) the user references "the function" / "that file" without a concrete path; (c) the user describes a goal without a verifiable done signal. These signal patterns are guidance, not a hard rule; the user can always override mode via argument. Done when: the mode is promoted or the signals are absent.

12. Question shape (every asking mode). Fire clarifying questions via the ask-user tool. The per-fire cap is 4; for larger sets fire multiple sequential batches ordered by dependency (batch mode uses the frontier-round rule in step 10 instead). Per question: a full sentence ending in ?; a header chip ≤ 12 characters; multiSelect false for single-pick mutually-exclusive axes, true only for additive subset picks (feature toggles, optional sub-tasks). Per option: a 1–5 word label with (Recommended) appended to and placed first for the recommended choice; a one-sentence trade-off description; an optional preview (markdown or monospace box) for visual comparisons, single-select only, skipped when the difference is purely conceptual. Never add an explicit "Other" option; free-text "Other" is auto-provided on every question, and free-text notes go in the annotations response field. Use this tool only to clarify requirements or choose between approaches during planning, not to ask "is the plan ready?". Done when: every fired question follows the shape.

13. Antipattern: never generate an override-checklist. Never emit a single multiSelect: true checklist where unticked means "default stands"; it collapses independent axes into one list. When the brief calls for the user to rarely have to type, route the intent into N per-axis single-select questions (≤ 4 per fire), each axis's (Recommended) option carrying the default. Reserve multiSelect strictly for additive picks. Done when: no override-checklist is emitted.

14. VS render timing. Render the VS block immediately before the first question fire of a planning session; subsequent intra-session fires need not repeat the VS preamble unless the survivor set materially changed. Done when: the VS block precedes the first fire.

15. Harness mapping. If the harness exposes only single-question prompts, fire them sequentially in dependency order; the shape (clarifying questions with one Recommended each) is what matters, and batching is an optimization. Map (Recommended) to whatever default-marker convention the harness uses; the rationale belongs in the description body either way. If no multi-pick mechanism exists, decompose additive picks into N independent single-selects. Done when: questions are fired through whatever mechanism the harness exposes.

16. Stop. Terminate when the mode's terminal holds: exhaustive: every clarifying question answered or discharged and intent confirmed; collaborative: the user signals convergence; adversarial: every fork resolved; batch: frontier empty and shared understanding confirmed; interview: record approved and written; scan: no open manual finding and the report emitted; proposal: the user replied yes, correction, or adjust. Do not proceed on non-trivial changes without visible VS (exhaustive, batch) or completed fork resolution (adversarial, batch). Done when: the terminal for the selected mode holds.

Failure and recovery

• Unresolved fork or blocking unknown (adversarial, batch): stop; report the blocking unknown and the unresolved fork. Do not assume an answer or descend into children.
• User answer contradicts a falsifier (batch): update the survivor set, adjust the design-tree roots, and recompute the frontier. Do not discard already-settled answers.
• No clear leader after broadened sampling (exhaustive): broaden sampling further or surface the decision point with concrete options and trade-offs. Do not silently pick.
• Fact lookup fails or is inconclusive (batch, scan): mark the prerequisite unsettled or tier the finding normally (usually manual); continue the rest of the frontier or scan. Never ask the user for a fact that can be looked up, and never guess a fact to avoid asking.
• No identifiable scan target after one read of the context (scan): stop and ask exactly one question naming what to scan. Classify nothing and emit no report; scanning nothing is a failure, not an empty result.
• Partial scan (scan): emit the findings found so far, name the excluded span, and do not claim done.
• Manual questions left unanswered (scan): the open manual findings remain; state that clarification is incomplete and list their ids. The done predicate does not hold.
• Empty goal (interview): ask for the goal before proceeding; stop if the user declines to supply one.
• User abandons or asks to implement mid-interview (interview): end the interview with no file written and report "no decision recorded", or decline and redirect back to the interview until the record is approved.
• Decision log written before approval (interview): delete the file. The log is written only after explicit user approval.
• Data too thin to propose from (proposal): say so and stop. Do not fall back to asking.
• User composes the ask from scratch (proposal): the proposal was wrong or a question in disguise; redo the proposal grounded in the data.
• User refuses to answer or signals non-convergence: record the discharged questions and the open ambiguity. Do not pretend intent is confirmed, and do not act on a partial understanding.
• Ask-user tool unavailable: fall back to sequential single-question chat prompts in dependency order; if no question tool exists at all, emit the question set as chat text and await replies.
• Partial-result rule: a partially answered batch is not done; re-fire only the unanswered axes, not the whole batch.
• Non-mutation rule: only interview mode writes, and only the approved decision log file; every other mode changes conversation state only. Recovery is re-asking or re-running the scan, never rollback. The blocked or non-converged result is an explicit list of open ambiguities and discharged questions, not a fabricated confirmation.

Output

Per mode, chat output only except where named. Exhaustive, collaborative, adversarial, and batch emit the VS block (once, before the first fire), the batched question sets, and a terminal intent summary stating the consolidated direction, assumptions, and discharged questions; batch additionally ends on the user's confirmation of shared understanding. Scan emits a findings report grouped by tier with manual last, one block per finding with fields id, quote (the exact ambiguous span), tier, recommendation (— for fyi), and basis; gated recommendations marked locked-unless-overridden, manual non-locking, auto resolutions compact with their basis; plus the manual questions fired and the CONCEPTS.md candidates; on explicit request for structured output, one fenced clarify-findings/v1 block containing a YAML list of the per-finding fields. Interview emits the presented decision log, then writes the approved record to DECISION-LOG.md or a user-named file. Proposal emits the one-line intent proposal, the next-step sketch, and the confirm/correct/adjust prompt.