| name | discovery |
| description | Explore a vague idea through Q&A — capture what good looks like as an interview record for /orb:spec |
| argument-hint | [topic] |
| allowed-tools | AskUserQuestion Read Edit Write Glob Grep |
/orb:discovery
Explore a vague idea or requirement through questioning. Use this when there's no card yet, or the card is thin (< 3 scenarios). The outcome is clarity — what good looks like, captured as an interview record ready for /orb:spec.
Usage
/orb:discovery [topic]
When to Use
- No card exists for this topic
- A card exists but has < 3 scenarios (not enough to design against)
- The problem space is unclear and needs open exploration
If a well-formed card exists (≥ 3 scenarios), use /orb:tabletop instead.
Instructions
1. Setup
- Determine the topic from the author's input
- Check
.orbit/cards/ for any related feature cards. If a thin card exists, read it as starting context.
- Identify the output directory:
.orbit/specs/YYYY-MM-DD-<topic-slug>/ (create if needed)
2. Search for Prior Art
Before asking questions, run a keyword scan (see /orb:keyword-scan) against .orbit/specs/ and .orbit/choices/ using terms from the topic. If prior specs or decisions already explored this area, front-load what they found — the discovery session should build on existing knowledge, not rediscover it.
3. Conduct the Discovery
Adopt the interviewer role (see /orb:interviewer for the full persona and the decision-level gate).
The author's job is to define what good looks like. Discovery questions stay at the intent level — goals, users, constraints, success criteria. Implementation questions are recorded as notes, not asked.
Target: 6–10 questions covering:
- Goal: What are we trying to achieve? What does success look like?
- Users: Who has this need? What's their context?
- Constraints: Platform, performance, compatibility, budget
- Success criteria: How will we know it works?
- Scope: What's in, what's explicitly out?
- Prior art: Are there existing approaches worth studying?
For each question:
-
Present the question using AskUserQuestion with contextually relevant suggested answers:
- Binary questions: use the natural choices
- Technology choices: suggest common options for the context
- Open-ended questions: suggest representative answer categories
- The author can always type a custom response
-
Record the Q&A pair in your working notes
-
After each answer, target the biggest remaining source of ambiguity
4. Questioning Strategy
- Always end responses with a question
- Target the biggest source of ambiguity
- Build on previous responses
- Be specific and actionable
- Use ontological questions: "What IS this?", "Root cause or symptom?", "What are we assuming?"
- You are ONLY a questioner — never write code, edit files, or run commands
- Continue until the author says "done" or requirements are clear
5. Ambiguity Assessment
After every 3-4 questions, assess clarity across three dimensions:
- Goal Clarity: Is the objective specific and well-defined?
- Constraint Clarity: Are limitations and boundaries specified?
- Success Criteria Clarity: Are success criteria measurable?
If all three are clear (ambiguity ≤ 0.2), suggest wrapping up.
6. Surface Decisions
During discovery, choices between approaches will surface. When a clear choice is made:
- Note it in the record under Decisions Surfaced
- Each entry should name the choice, the alternatives considered, and the rationale
- These become MADR decision records during or after the session (the spec will reference them)
7. Save the Record
Save the Q&A as: .orbit/specs/YYYY-MM-DD-<topic-slug>/interview.md
# Discovery: <Topic>
**Date:** YYYY-MM-DD
**Interviewer:** <agent name>
**Card:** .orbit/cards/NNNN-slug.yaml (if applicable)
**Mode:** discovery
---
## Context
<Initial topic/idea description>
## Q&A
### Q1: <Short label>
**Q:** <question>
**A:** <answer>
[...]
---
## Summary
### Goal
<Extracted goal statement>
### Constraints
- <constraint 1>
### Success Criteria
- <criterion 1>
### Decisions Surfaced
- <choice made>: chose X over Y because Z (→ .orbit/choices/NNNN if recorded)
### Implementation Notes
- < — >
Next step: /orb:spec to generate a structured specification from this discovery.
