gathering-requirements

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