diegosouzapw Interview workflow
Purpose
Gather user decisions, preferences, or clarifications through a structured one-question-at-a-time process. This prevents overwhelming the user and ensures each answer is properly understood before moving on.
Rules (strict)
- One question per message. Never batch multiple questions.
- Present clear options. Each question should have labeled options (A, B, C) or a clear format for the expected answer.
- Explain briefly. Give just enough context for the user to decide—not a wall of text.
- Record immediately. After each answer, note it in
.agent/focus.mdor a working document before asking the next question. - Allow escape. User can say "skip", "defer", "use your recommendation", or "stop interview".
- Summarize at end. When all questions are answered, present a summary for confirmation.
Interview state tracking
Track in .agent/focus.md under "Doing now":
## Doing now
Interview: [topic]
- Q1: [question summary] → [answer or pending]
- Q2: [question summary] → [answer or pending]
- ...
Procedure
- Setup: List all questions internally (do not show to user yet).
- Ask Q1: Present one question with options.
- Wait: Do not proceed until user responds.
- Record: Update focus.md with the answer.
- Ask Q2: Repeat until all questions answered or user stops.
- Summarize: Present all answers for confirmation.
- Proceed: Use confirmed answers to continue the workflow.
Handling special responses
| User says | Action |
|---|---|
| "skip" | Mark as SKIPPED, move to next question |
| "defer" | Mark as DEFERRED, move to next question |
| "use your recommendation" | Apply the agent's recommended default, note it |
| "stop" / "pause" | End interview, save progress, can resume later |
| "go back" | Re-ask the previous question |
| unclear answer | Ask a brief clarifying follow-up (still counts as same question) |
Question Quality Standards
Good Questions
- Specific to context — Reference project details, not generic templates
- Reveal non-obvious decisions — Probe tradeoffs and implications
- Uncover edge cases — "What happens when X fails?"
- Challenge assumptions gently — "You mentioned X; does that mean Y?"
- Build on previous answers — Show you listened
Bad Questions (avoid)
- ❌ Too obvious: "What programming language will you use?"
- ❌ Too generic: "Do you need a database?"
- ❌ Trivial: "What color should the button be?"
- ❌ Already answered: Re-asking what user just said
- ❌ Assumptive: Leading questions that presume an answer
Multi-Option Format
When presenting choices, use label + description:
**Q3: How should the system handle conflicting edits?**
A) **Last-write-wins** — Simple, but may lose data. Best for low-conflict scenarios.
B) **Optimistic locking** — Detect conflicts, prompt user to resolve. More complex.
C) **CRDT-based merge** — Automatic conflict resolution. Best for real-time collab.
D) **Manual review queue** — Flag conflicts for human review. Best for critical data.
This format helps users make informed decisions without lengthy explanations.
Completion Criteria
Interview is complete when:
- All planned questions answered (or explicitly skipped/deferred)
- No obvious gaps in the information gathered
- User confirms summary is accurate
- Answers are recorded in appropriate state file
Anti-patterns (never do)
- ❌ Asking multiple questions in one message
- ❌ Presenting all questions upfront as a "form"
- ❌ Proceeding without waiting for an answer
- ❌ Long explanations that bury the actual question
- ❌ Forgetting to record answers
- ❌ Asking generic template questions regardless of context
- ❌ Ignoring previous answers when forming next question