Gathering Requirements

When to Use

• •User specifying HOW they want something done
• •Clarifying preferences or constraints
• •Understanding WHAT needs to be built
• •Gathering specifications before work begins
• •Building on existing systems (enhancement, integration)

Core Workflow

1. Classify Request Type

Ask 1-2 quick questions to understand context:

Q1: What type of work?

1. •New feature - Building from scratch
2. •Enhancement - Improving existing functionality
3. •Integration - Connecting external system
4. •Refactor - Changing implementation without behavior change

Q2: Current knowledge level?

• •Clear vision - User knows exactly what they want
• •General idea - Goal clear, implementation details fuzzy
• •Exploring options - Uncertain about approach

2. Pre-Investigation (If Needed)

When to investigate first:

• •Enhancing existing feature (understand current implementation)
• •Integration unclear (explore existing patterns)
• •Technical constraints unknown (investigate capabilities)
• •Building on existing architecture

When to skip investigation:

• •Green field feature (nothing exists yet)
• •Complete requirements already provided
• •Simple, clear scope with no dependencies

Delegate async investigation agents to understand existing system. Results saved in agent-responses/.

Transform findings into informed questions:

• •❌ Generic: "What authentication methods do you want?"
• •✅ Informed: "I see JWT with refresh tokens. For MFA: TOTP app? SMS codes? Required for all users or optional?"

3. Universal Discovery Questions

Ask these core questions for any feature (adapt to context):

UQ-1: Happy Path "Describe the successful scenario step-by-step from the user's perspective."

• •What triggers the feature?
• •What actions does user take?
• •What's the desired outcome?

UQ-2: Edge Cases & Constraints "What should happen for these scenarios?"

• •Empty state (no data)
• •Huge dataset (performance)
• •Invalid input (validation)
• •Network failure (offline)
• •Concurrent actions (conflicts)

UQ-3: Performance Expectations "How should this feel to the user?"

• •Instant (<100ms) - UI updates, simple operations
• •Fast (<1s) - API calls, data fetching
• •Eventual (loading indicator) - Heavy processing
• •Background (no waiting) - Async operations

UQ-4: Failure Modes "What should NEVER happen? What would frustrate users most?"

• •Data loss scenarios
• •Breaking existing workflows
• •Confusing error states

UQ-5: Scope Boundaries "What's explicitly OUT of scope for this iteration?"

• •Future enhancements
• •Advanced features
• •Edge cases to defer

UQ-6: Integration Points "How does this interact with:"

• •Existing features
• •External APIs or services
• •Database or storage
• •Authentication/authorization
• •Third-party libraries

4. Feature-Specific Discovery

Tailor questions based on feature type (select relevant):

Authentication/Authorization:

• •Credentials: Email/password? Social login? Magic link? 2FA/MFA?
• •Session: Duration? Remember me?
• •Password: Length/complexity requirements?
• •Failed login: Generic error / account lock / CAPTCHA / rate limit?
• •MFA: TOTP app? SMS? Email? Required or optional?

CRUD Operations:

• •Validation: Required fields? Format rules? Length limits? Unique constraints?
• •Concurrent edits: Last write wins / show conflict / lock?
• •Delete: Hard delete / soft delete / confirmation / undo?
• •Saves: Wait for server / optimistic update / show saving?

Search & Filter:

• •Scope: Search specific fields / all text / metadata?
• •Timing: Live as typing / after pause / on Enter?
• •Matching: Exact / contains / fuzzy / full-text?
• •Sorting: Relevance / alphabetical / recent / user-selectable?

Forms & Input:

• •Validation timing: On blur / on submit / as typing?
• •Error display: Inline / summary / toast?
• •Unsaved changes: Warning / auto-save / allow losing data?
• •Defaults: Previous values / smart defaults / empty / pre-populated?

Real-time Features:

• •Mechanism: Polling / WebSocket / Server-Sent Events?
• •Frequency: 1 second / 5-10 seconds / 1 minute / event-driven?
• •Offline: Queue actions / block usage / show offline mode?
• •Conflict: Show notification / auto-merge / manual resolution?

File Upload:

• •Types & limits: Images only / docs / any file? Max size?
• •Multiple files: One at a time / simultaneous / batch?
• •Progress: Show progress bar / allow cancel?
• •Storage: Where stored? CDN? S3? Local?

Data Visualization:

• •Chart type: Bar / line / pie / scatter / custom?
• •Interactivity: Hover tooltips / click drill-down / zoom / pan?
• •Responsive: Mobile behavior? Simplified view?
• •Export: Download as image / CSV / PDF?

5. Resolve All Unknowns

Step 5a: Generate Technical Inferences Internally

Document assumptions with confidence levels:

• •HIGH: User explicitly stated / only reasonable approach / industry standard / security requirement
• •MEDIUM: Common practice but alternatives exist / implied by requirements / standard pattern
• •LOW: Filling implementation gap / multiple valid approaches / assumption about preference

Step 5b: Present Inferences for Confirmation

"Based on our discussion, here are my technical assumptions:

High Confidence (will implement unless you object):

• •[Assumption with reasoning]

Medium Confidence (common approach, alternatives exist):

• •[Assumption - alternative: X]

Low Confidence (need your input):

• •[Question with proposed approach]

Any objections or preferences?"

Step 5c: Resolve All Clarifications

Ask follow-up questions for remaining unknowns. Do not proceed to Step 6 until ALL inferences are confirmed and ALL clarifications are resolved.

6. Create Requirements Specification

Use the canonical template at ~/.claude/file-templates/requirements.template.md.

Instructions:

• •Fill out every section with CONFIRMED information only
• •Document decisions in "Implementation Notes" with reasoning
• •Cross-reference relevant docs in docs/; create stubs if missing
• •Ensure "Relevant Files" section is comprehensive
• •Include "Artifacts" section referencing existing system findings

7. Present & Confirm Final Specification

"Here's the requirements specification based on our confirmed decisions:

[Show or link to requirements file]

All technical decisions and clarifications have been incorporated. Ready to proceed to planning/implementation?"

Wait for user approval before next phase.

8. Update Project Documentation

If project has docs structure:

Update docs/product-requirements.md:

• •Add feature with next Feature ID (F-##)
• •Include requirements summary
• •Add acceptance criteria
• •Link to related features and integration points

Reference:

• •docs/system-design.md - Architecture context
• •Investigation findings from agent-responses/agent_<id>.md

Quick Reference

Essential Questions:

1. •Happy path scenario
2. •Key edge cases & performance expectations
3. •Failure modes
4. •Out of scope items
5. •Integration points

Investigation Artifacts:

• •Input: docs/product-requirements.md, docs/system-design.md
• •Output: Requirements specification + updated project docs

Confidence Levels:

• •HIGH: Explicit requirement or best practice
• •MEDIUM: Standard practice with alternatives
• •LOW: Turn into question for user

Common Pitfalls

• •❌ Asking questions without understanding existing system
• •❌ Proceeding to implementation with unresolved ambiguities
• •❌ Mixing assumptions with confirmed requirements
• •❌ Skipping edge case discovery
• •✅ Investigate first → ask informed questions → resolve all unknowns → document → confirm