refining-requirements

Requirements Refiner

Clarify ambiguous requirements through structured questioning and produce detailed, implementation-ready specifications.

When to Use This Skill

Use PROACTIVELY when:

• User has a rough product idea or feature memo to refine
• Requirements contain ambiguous or unclear points
• Specifications need clarification before implementation
• User mentions: requirements, PRD, specs, refine, detail, clarify

After this skill: Use designing-wireframes for UI/UX visualization, then planning-tickets for GitHub Issues.

Workflow

Phase 1: Read & Understand
    |
Phase 2: Identify Ambiguities
    |
Phase 3: Question Rounds (AskUserQuestion)
    |
Output: Detailed requirements document

Phase 1: Read & Understand

1. Read the provided requirements document
2. Understand the core value proposition
3. Identify the target user and their pain points
4. Note the technical stack and constraints

Phase 2: Identify Ambiguities

Systematically check for ambiguities in these categories:

UI Components

UX Flows

Business Logic

Mobile UX (MUST CHECK for mobile apps)

Accessibility (MUST CHECK)

Error Prevention & Recovery

Visual Design

Phase 3: Question Rounds

Use AskUserQuestion tool to clarify ambiguities. Group related questions (max 4 per round).

Question Design Principles

1. Provide concrete options - Don't ask open-ended questions
2. Include trade-offs - Explain what each option means
3. Use descriptive headers - Short, scannable labels (max 12 chars)
4. Batch related questions - Group by topic area

Example Question Categories

UI Style Questions:

- Size selection UI format?
  -> Bottom Sheet / Modal / Inline Expansion

- Button design?
  -> Icon+Text / Icon only / Text only

- List display format?
  -> Grouped / Flat

Behavior Questions:

- Display when over 100%?
  -> Cap at 100% / Show excess in different color / Ring format

- Delete confirmation?
  -> With confirmation / Without confirmation

- Error behavior?
  -> Warn and continue / Block

Navigation Questions:

- Screen access method?
  -> Tab bar / Header icon / In-screen link

- Onboarding steps?
  -> 1 screen / 3 steps / 4 steps

Pro/Free Questions:

- Paywall display timing?
  -> On feature tap / At boundary reached

- Paywall UI?
  -> SDK standard / Custom

Mobile UX Questions (CRITICAL for mobile apps):

- Primary action button placement?
  -> Bottom (Thumb-Zone) fixed / Center / Within content

- Loading display format?
  -> Simple spinner / Skeleton Screen / Content Shimmer

- Haptic Feedback?
  -> Implement (on success, warning) / Don't implement

Accessibility Questions (MUST ASK):

- Accessibility requirements?
  -> WCAG AA compliance / Basic support only / Not in MVP

- VoiceOver/TalkBack support?
  -> Full support / Basic (accessibilityLabel) / Not in MVP

Error Prevention Questions:

- Delete operation UX?
  -> Immediate (no confirmation) / Toast with Undo / Confirmation dialog

- Define detailed validation rules?
  -> Define (specify char count, range, etc.) / Decide at implementation

- Error display format?
  -> Toast / Alert / Inline message

Visual Design Questions:

- Dark mode support?
  -> Light mode only (MVP) / Auto-follow system / Manual toggle

- Empty State display?
  -> Simple text / Icon + text / With CTA

After Questions: Document Update

After gathering all answers, update the requirements document with:

1. Detailed specifications for each feature
2. Edge case handling definitions
3. Default values for all settings
4. Validation rules if defined

Use the requirements-section.md template for consistent formatting.

Best Practices

Questioning

• Ask questions in rounds of 3-4 related topics
• Always provide 2-4 concrete options
• Include trade-off descriptions
• Don't ask about obvious decisions
• Skip questions if the document is already clear

Documentation

• Be specific, not vague
• Include default values
• Document edge cases
• Cross-reference related sections

Templates

• requirements-section.md - Feature section template

AI Assistant Instructions

When this skill is activated:

DO:

1. Read first - Always read the requirements document before asking questions
2. Use AskUserQuestion - Proactively clarify ambiguities
3. Batch questions - Group related questions (max 4 per round)
4. Provide options - Always give concrete choices, not open-ended questions
5. Update systematically - Edit the document section by section
6. Track progress - Use TodoWrite to track phases

MUST CHECK (for mobile apps):

1. Thumb-Zone Design - Ask about primary action button placement (bottom vs center)
2. Accessibility - Ask about WCAG compliance level, touch target sizes
3. Loading States - Ask how to display loading (spinner, skeleton, shimmer)
4. Error Handling UX - Ask about error display format (Toast, Alert, inline)
5. Haptic Feedback - Ask whether to implement vibration feedback
6. Delete UX - Ask about confirmation behavior (immediate, undo, dialog)
7. Form Validation - Ask about validation rules and error message format
8. Dark Mode - Ask about theme support (light-only, auto, manual)
9. Empty States - Ask about display format when no data exists

DON'T:

1. Make assumptions about UI/UX without asking
2. Ask more than 4 questions at once
3. Ask vague, open-ended questions
4. Leave edge cases undefined
5. Skip Mobile UX checks - These are often overlooked but critical
6. Skip Accessibility checks - WCAG compliance should be decided early
7. Skip Error Handling UX - Every app needs clear error feedback

Question Flow (Recommended Order):

1. Core UI decisions - Layout, navigation, basic components
2. Mobile UX - Thumb-zone, loading states, haptic feedback
3. Accessibility - WCAG level, touch targets, VoiceOver
4. Error handling & validation - Delete UX, form validation, error display
5. Visual design - Dark mode, empty states, animations
6. Pro/monetization - Paywall timing, feature gates

When Uncertain:

• Always ask the user rather than assume
• Provide 2-4 options with clear trade-offs
• Explain the implications of each choice

After Completion:

Suggest using designing-wireframes skill for UI/UX visualization if screens need to be designed.