Commit 8413d32

mo khan <mo@mokhan.ca>
2026-01-29 04:34:05
chore: add user stories for improving the interview tool
1 parent 6fb9752
.elelem/backlog/006-interview-question-types.md
@@ -0,0 +1,47 @@
+As an `agent`, I `want to ask questions with different answer types`, so that `I can collect structured responses while still allowing conversational flexibility`.
+
+# SYNOPSIS
+
+Add support for text, single-select, multi-select, and yes/no question types to the interview tool.
+
+# DESCRIPTION
+
+The interview tool currently only supports free-form text input. This story adds support for four question types:
+
+1. **text** - Open-ended free-form input (current behavior)
+2. **single** - Single selection from a list of options (radio-button style)
+3. **multi** - Multiple selections from a list of options (checkbox style)
+4. **yesno** - Boolean yes/no confirmation
+
+Even when structured options are presented, the user can always type free-form text instead. The agent should handle unexpected responses gracefully (e.g., if the user asks a clarifying question rather than selecting an option).
+
+Example API:
+```ruby
+interview(
+  question: "Pick a color",
+  type: "single",
+  options: ["Red", "Green", "Blue"]
+)
+```
+
+# SEE ALSO
+
+* [ ] lib/elelem/terminal.rb - Terminal input/output handling
+* [ ] lib/elelem/tool.rb - Tool definition structure
+
+# Tasks
+
+* [ ] TBD (filled in design mode)
+
+# Acceptance Criteria
+
+* [ ] Agent can specify `type: "text"` for free-form input (default behavior)
+* [ ] Agent can specify `type: "single"` with `options` array for single selection
+* [ ] Agent can specify `type: "multi"` with `options` array for multiple selection
+* [ ] Agent can specify `type: "yesno"` for boolean confirmation
+* [ ] Options are displayed as a numbered list (e.g., "1. Red", "2. Green", "3. Blue")
+* [ ] User can type a number to select an option
+* [ ] User can type free-form text instead of selecting a numbered option
+* [ ] For multi-select, user can enter comma-separated numbers (e.g., "1, 3")
+* [ ] For yes/no, accepts variations like "y", "yes", "n", "no" (case-insensitive)
+* [ ] Response returned to agent includes both the raw input and parsed selection(s)
.elelem/backlog/007-interview-batch-questions.md
@@ -0,0 +1,43 @@
+As an `agent`, I `want to ask multiple questions at once`, so that `I can collect related information in a single interaction like a form`.
+
+# SYNOPSIS
+
+Allow the interview tool to accept an array of questions and return all answers together.
+
+# DESCRIPTION
+
+Building on the question types feature, this story adds the ability to send a batch of questions in a single interview call. This is useful when the agent needs to collect several related pieces of information and it would be tedious to ask them one at a time.
+
+Example API:
+```ruby
+interview(questions: [
+  { question: "What's your name?", type: "text" },
+  { question: "Pick a color", type: "single", options: ["Red", "Green", "Blue"] },
+  { question: "Select features", type: "multi", options: ["Auth", "API", "UI"] },
+  { question: "Ready to proceed?", type: "yesno" }
+])
+```
+
+The questions are presented sequentially, and all answers are collected before returning to the agent. The user can still respond with clarifying questions or unexpected input on any individual question.
+
+The existing single-question API remains supported for backward compatibility.
+
+# SEE ALSO
+
+* [ ] .elelem/backlog/006-interview-question-types.md - Prerequisite: question types
+* [ ] lib/elelem/terminal.rb - Terminal input/output handling
+
+# Tasks
+
+* [ ] TBD (filled in design mode)
+
+# Acceptance Criteria
+
+* [ ] Agent can pass `questions` array with multiple question objects
+* [ ] Each question in the array can have its own type and options
+* [ ] Questions are presented to user one at a time in order
+* [ ] All answers are collected before returning to agent
+* [ ] Response includes an array of answers matching the question order
+* [ ] Single-question API (`question: "..."`) still works for backward compatibility
+* [ ] If user provides unexpected input on one question, that input is captured and interview continues
+* [ ] Agent receives enough context to understand which answer corresponds to which question
.elelem/backlog/008-interview-tui-selection.md
@@ -0,0 +1,42 @@
+As a `user`, I `want to navigate options with arrow keys`, so that `I can quickly select from a list without typing numbers`.
+
+# SYNOPSIS
+
+Add TUI-style interactive selection widgets for single and multi-select questions.
+
+# DESCRIPTION
+
+When the terminal supports it, present single-select and multi-select questions as interactive widgets where the user can:
+
+- Use **arrow keys** (up/down) to navigate between options
+- Press **space** to toggle selection (for multi-select)
+- Press **enter** to confirm selection
+
+This provides a smoother experience than typing numbers, especially for longer option lists. The numbered fallback (from story 006) remains available for terminals that don't support the TUI widgets or when the user starts typing text instead of navigating.
+
+The widget should be visually clear:
+- Highlight the currently focused option
+- Show a marker (e.g., `[x]` or `●`) for selected options
+- For single-select, selection and confirmation can be combined (enter selects and confirms)
+
+# SEE ALSO
+
+* [ ] .elelem/backlog/006-interview-question-types.md - Prerequisite: question types with numbered fallback
+* [ ] lib/elelem/terminal.rb - Terminal capabilities and input handling
+* [ ] Reline library - May provide building blocks for TUI input
+
+# Tasks
+
+* [ ] TBD (filled in design mode)
+
+# Acceptance Criteria
+
+* [ ] Single-select questions show an interactive list when terminal supports it
+* [ ] User can press up/down arrows to move highlight between options
+* [ ] User can press enter to select the highlighted option (single-select)
+* [ ] Multi-select questions allow space to toggle selection on highlighted option
+* [ ] Multi-select shows visual indicator for selected items (e.g., `[x]`)
+* [ ] Pressing enter on multi-select confirms current selections
+* [ ] If user starts typing text, widget gracefully switches to free-form input mode
+* [ ] Falls back to numbered list input if terminal doesn't support TUI features
+* [ ] Works correctly when terminal is resized during interaction