Error in user YAML: (<unknown>): did not find expected key while parsing a block mapping at line 1 column 1

---
description: Comprehensive requirements discovery via iterative questioning
argument-hint: "topic to clarify" [--max-iterations N]
---

Ralph Clarify: Iterative Discovery Loop

Use the Ralph loop to exhaustively gather requirements through structured questioning. The loop pressure overrides the natural tendency to stop asking after 3-5 questions.

Parse Arguments

Arguments: $ARGUMENTS

Split arguments:

• TOPIC: Everything before -- flags (what we're clarifying)
• --max-iterations: Number (default: 30)

Setup

1. Create discovery file at .claude/clarify-session.md:

# Discovery: {TOPIC}

Started: {timestamp}

## Questions Asked

(Track all questions to avoid repetition)

## Answers Received

(Capture user responses)

## Emerging Requirements

(Synthesize as patterns emerge)

2. Start Ralph loop with discovery prompt:

/ralph-reviewed:ralph-loop "{DISCOVERY_PROMPT}" --max-iterations {N} --no-review --completion-promise "CLARIFIED"

Discovery Prompt

Build this prompt for the ralph-loop:

You are conducting comprehensive requirements discovery for: {TOPIC}

## Your Task

Use the AskUserQuestion tool to ask clarifying questions. Keep asking until you have exhaustively covered all aspects needed to create a complete plan.

## Each Iteration

1. Read `.claude/clarify-session.md` for questions already asked
2. Identify gaps in understanding
3. Ask 2-4 NEW questions via AskUserQuestion (never repeat)
4. After user answers, update `.claude/clarify-session.md`:
   - Add questions to "Questions Asked"
   - Add answers to "Answers Received"
   - Update "Emerging Requirements" with new insights
5. Continue to next iteration

## Question Categories to Cover

Work through these systematically (not all at once):

**Core Requirements**
- What must this do? What's the minimum viable version?
- What's explicitly out of scope?

**Users & Context**
- Who uses this? What's their skill level?
- What environment/constraints exist?

**Integration Points**
- What existing systems does this touch?
- What data flows in/out?

**Edge Cases**
- What happens when things go wrong?
- What are the boundary conditions?

**Quality Attributes**
- Performance requirements?
- Security considerations?

**Existing Patterns**
- How do similar things work in this codebase?
- What conventions should we follow?

**Preferences**
- Any strong opinions on approach?
- Tradeoffs: simplicity vs flexibility vs performance?

## Question Design

Use AskUserQuestion effectively:
- 2-4 options per question (not too many)
- Include "Other" implicitly (tool provides it)
- Group related questions in one call (max 4 questions per call)
- Make options concrete, not vague

Example:

questions: [ { question: "How should we handle authentication failures?", header: "Auth errors", options: [ { label: "Redirect to login", description: "Clear session and send to /login" }, { label: "Show inline error", description: "Display error message, keep user on page" }, { label: "Retry silently", description: "Attempt token refresh before showing error" } ], multiSelect: false } ]

## Completion Criteria

Output <promise>CLARIFIED</promise> ONLY when:
- You've covered all question categories above
- You've asked follow-up questions on complex answers
- You genuinely cannot think of more meaningful questions
- The discovery file has comprehensive requirements

Typical sessions: 40-70 questions across 15-25 iterations.

## If User Says "Enough"

If the user indicates they want to stop (selects "enough", "stop", "let's move on"):
- Summarize what you've learned in the discovery file
- Note any gaps that remain
- Output <promise>CLARIFIED</promise>

## Output Location

All discoveries saved to: `.claude/clarify-session.md`

This file can be referenced by subsequent /ralph or /ralphoff commands for implementation.

Confirmation

After setup, output:

Starting comprehensive discovery for: {TOPIC}

This will use iterative questioning to gather requirements exhaustively.
Expect 40-70 questions across multiple categories.

Discovery file: .claude/clarify-session.md

To stop early, answer any question with "enough" or "let's move on".

Beginning discovery...

Then immediately start the ralph-loop with the discovery prompt.