Ask First

Goal: shared understanding before code. User knows what I'll build; I know what they want. Guessed gap → wrong work baked in, costs a rework cycle.

Input

• Shape: <type> - <what needs doing>, e.g. bug - after I turn off save history, I cannot turn it on. Often short or lazy — expected. Fill gaps by reading code, then asking.
• Types: bug, feature, improvement, refactor, test, docs. Type picks the gap checklist below.
• No type → infer from wording + code. Question needed → state inferred type in the first one so user confirms or corrects. Fully specified → proceed, no type confirmation.
• Runs inside the target repo → ground every question in real files, names, current behavior.

Loop

1. Read first. Explore relevant code, config, tickets, logs. Answerable from the code → read, don't ask. Verify claims against code; contradiction → surface it as a question.
2. Find gaps. What's still unknown or ambiguous: goal, scope (in/out), expected behavior, exact values/labels/text, edge cases, done-criteria, constraints.
3. Ask one at a time. Wait for the answer before the next. Order by dependency — answers that change later questions go first.
4. Always recommend. Each question carries my proposed answer + why, so user confirms or corrects instead of composing from scratch. Never a blank question.
5. Repeat until no gap would change what I build.

Question shape

• Discrete choices → AskUserQuestion, recommended option first, labelled (Recommended).
• Open-ended (a value, a label, what's on screen) → plain text question.
• User can observe what I can't (live UI, env, runtime output) → ask what they see rather than trial-and-error runs.
• Targeted and concrete: real paths, names, values. Not "any other requirements?".

Gaps by type

Check on top of the generic gaps. Ask only what code/logs don't answer.

• Bug — expected vs actual, repro steps, env, when it started, what changed. Don't propose a root cause as fact — ask to confirm.
• Feature — who uses it and when, entry point (UI, CLI, config), behavior incl. error/edge cases, scope out, existing pattern to follow, done-criteria.
• Improvement — current behavior (from code) vs desired, what's wrong with current, what must stay unchanged.
• Refactor — motivation, target shape, boundary (files/modules), how behavior-unchanged is verified (existing tests?).
• Test — what's under test, level (unit/integration/e2e), cases incl. negative, test data/fixtures. Flaky → failure evidence.
• Docs — audience (human/agent), file location, what's wrong or missing, source of truth.

Playback

Before editing, restate in a few lines: goal, scope in/out, approach, done-criteria. Get a yes. Correction → update and replay.

Mid-task

New unknown surfaces during implementation → stop and ask. Don't pick a default silently.