Requirements Gathering

What It Does

•Loads product context (mission, roadmap, tech-stack)
•Asks 4-8 targeted questions (ONE at a time)
•Requests visual assets and reusability info
•Mandatory: Checks visuals folder via bash
•Asks follow-ups if needed (ONE at a time)
•Documents everything in requirements.md

The Process

Step 1: Load Context

bash

SPEC="[provided by workflow]"

# Read initial idea
cat "$SPEC/planning/initialization.md"

# Read product context
cat specs/product/mission.md
cat specs/product/roadmap.md
cat specs/product/tech-stack.md

Analyze:

•User's feature description
•How it fits product mission
•Where in roadmap
•Technical constraints

Step 2: Generate Questions

Create 4-8 questions based on feature and context.

Question guidelines:

•Number each question
•Propose sensible defaults
•Frame as "I'm assuming X, correct?"
•Make it easy to confirm or suggest alternatives
•Use multiple choice when options clear

CRITICAL: Always end with:

•Visual assets request
•Reusability question

Present:

code

Based on [feature], I have clarifying questions:

1. [Question with assumption]

[ONE question at a time from here...]

After first question answered, ask second:

code

2. [Next question]

Continue ONE at a time until all questions asked.

Then end with:

code

**Existing Code Reuse:**
Similar features in your codebase we should reference?

Examples:
- Similar UI components/layouts
- Related backend logic/services
- Existing models/controllers with similar functionality

Provide paths/names if any exist.

**Visual Assets:**
Have design mockups, wireframes, or screenshots?

If yes, place in:
`[spec]/planning/visuals/`

Names like:
- homepage-mockup.png
- form-wireframe.jpg
- mobile-view.png

Please answer.

STOP. Wait for response.

Step 3: Process Answers

Store exact responses.

MANDATORY: Check for visuals

bash

# ALWAYS run regardless of user's response
ls -la "$SPEC/planning/visuals/" 2>/dev/null | \
  grep -E '\.(png|jpg|jpeg|gif|svg|pdf)$' || \
  echo "No visual files found"

If files found:

bash

# Read each visual
for file in "$SPEC/planning/visuals/"*; do
  # Use Read tool
  # Note: design elements, fidelity level
done

Analyze:

•Layout, components, colors
•User flow implications
•Check filename for: lofi, lo-fi, wireframe, sketch, rough
•Match with requirements discussed

Step 4: Determine Follow-ups Needed

Trigger follow-ups if:

Visual-triggered:

•User didn't mention visuals but files exist
•Filename suggests wireframe (clarify fidelity)
•Visuals show features not discussed

Reusability-triggered:

•User didn't provide similar features but seems common
•Provided paths seem incomplete

Answers-triggered:

•Vague requirements
•Missing technical details
•Unclear scope

Step 5: Ask Follow-ups (if needed)

ONE question at a time:

Visual discovery:

code

Found in visuals folder:
- homepage-layout.png
- form-wireframe.jpg

The wireframe filename suggests low-fidelity.

Should I treat these as:
1. Layout/structure guides (use existing styling)
2. Exact design specs (match precisely)

Which?

Reusability:

code

You mentioned similar forms exist.

Could you point me to:
- Path to existing form component
- Any service objects with similar logic

This helps ensure consistency.

Clarification:

code

You mentioned "admin controls" - could you clarify:

Should admins:
1. View only
2. View + edit
3. View + edit + delete
4. Something else

Which?

STOP after each follow-up. Wait for response.

Step 6: Save Requirements

After all questions answered:

bash

cat > "$SPEC/planning/requirements.md" <<'EOF'
# Spec Requirements: [Feature Name]

## Initial Description
[From initialization.md]

## Requirements Discussion

### First Round Questions

**Q1:** [Question]
**Answer:** [Exact answer]

**Q2:** [Question]
**Answer:** [Exact answer]

[All questions and answers]

### Existing Code to Reference

[If user provided paths/names:]
**Similar Features:**
- Feature: [Name] - Path: `[path]`
- Components to reuse: [description]

[If none provided:]
No similar features identified - spec-writer will search codebase.

### Follow-up Questions

[If any asked:]
**Follow-up 1:** [Question]
**Answer:** [Answer]

## Visual Assets

### Files Provided:
[Based on bash check, NOT user statement]

- `filename.png`: [What it shows from analysis]
  - Fidelity: [high-fidelity / low-fidelity wireframe]
  - Key elements: [list]

[If no files:]
No visual assets provided.

### Visual Insights:
[If files exist:]
- Design patterns: [list]
- User flow: [description]
- UI components: [list]

## Requirements Summary

### Functional Requirements
- [Core functionality]
- [User actions]
- [Data management]

### Reusability Opportunities
- [From user input]

[If none:]
Will search codebase during spec writing.

### Scope Boundaries

**In Scope:**
- [What will be built]

**Out of Scope:**
- [What won't be built]
- [Future enhancements]

### Technical Considerations
- [Integration points]
- [Constraints]
- [Tech preferences]
EOF

Step 7: Report Completion

code

✅ Requirements complete!

Documented:
- [X] questions and answers
- Visuals: [Y found / None]
- Reusability: [Z identified / Search later]
- Functional requirements
- Scope boundaries

Created: planning/requirements.md

Ready for Phase 3: Spec writing

Return to workflow.

Question Pattern Examples

With defaults:

code

1. I'm assuming users need authentication.
   Correct, or should it be publicly accessible?

Multiple choice:

code

2. For data storage:

A. New database table (unique data)
B. Extend existing table (related entities)
C. Use existing table (just relationships)

Which, or different approach?

Open-ended:

code

3. Tell me the user workflow:
- Starting point?
- Steps they take?
- End result they see?

Red Flags

Never:

•Ask multiple questions in one message
•Skip visual folder check
•Assume visuals without bash check
•Proceed without answers
•Modify user's responses

Always:

•Ask ONE question at a time
•Run bash command for visuals
•Analyze any visual files found
•Store exact answers
•Check filenames for fidelity indicators

Integration

Called by:

•spec-creation-workflow (Phase 2)

Returns to:

•spec-creation-workflow

Creates:

•[spec]/planning/requirements.md

Next phase uses:

•requirements.md for spec writing
•Visual files for design guidance
•Reusability notes for codebase search