gh-igpastor-sng-claude-marketplace-plugins-sngular-pm/skills/requirements-gathering/SKILL.md

Requirements Gathering Skill

This skill enables Claude to autonomously gather, analyze, and document requirements for features, projects, or issues.

When to Use This Skill

Use this skill when:

• A user describes a feature but hasn't provided detailed requirements
• Converting vague ideas into structured specifications
• Analyzing an issue and determining what needs to be built
• Preparing for development planning
• Creating GitHub issues from conversations

What This Skill Does

1. Elicits Requirements Through Questions

   • Asks clarifying questions about scope and goals
   • Identifies functional and non-functional requirements
   • Discovers constraints and dependencies
   • Clarifies success criteria

2. Analyzes Context

   • Reviews existing codebase patterns
   • Checks for similar implementations
   • Identifies affected components
   • Reviews related documentation

3. Structures Requirements

   • Organizes into functional/non-functional categories
   • Defines clear acceptance criteria
   • Prioritizes using MoSCoW method
   • Creates user stories where applicable

4. Documents Findings

   • Generates structured requirements document
   • Creates GitHub-compatible markdown
   • Includes technical specifications
   • Adds implementation considerations

Usage Process

Step 1: Initial Analysis

When a user describes a feature:

User: "I want to add user authentication"

Claude should:

1. Acknowledge the request
2. Start gathering context from the codebase
3. Begin asking clarifying questions

Step 2: Ask Clarifying Questions

Essential questions to ask:

• What type of authentication? (OAuth, JWT, Session-based)
• Who are the users? (Internal staff, external customers, admins)
• What features need protection?
• Any specific security requirements?
• Integration with existing systems?
• Password policies required?
• MFA/2FA needed?
• Social login options?

Step 3: Analyze Codebase

Search for:

• Existing authentication patterns
• Current user models
• API structure
• Frontend framework in use
• State management approach
• Database schema

Step 4: Structure Requirements

Create document following this format:

## Feature: User Authentication

### Business Context
- **Problem**: Users currently have no way to securely access the system
- **Goal**: Implement secure authentication for user access control
- **Success Criteria**: Users can register, login, and access protected resources

### Functional Requirements

#### FR-1: User Registration
**Priority**: Must-have
**Description**: Users can create new accounts with email and password
**Acceptance Criteria**:
- [ ] Registration form validates email format
- [ ] Password meets complexity requirements (min 8 chars, 1 uppercase, 1 number)
- [ ] Email confirmation sent upon registration
- [ ] Duplicate emails are rejected
- [ ] User data is stored securely in database

#### FR-2: User Login
**Priority**: Must-have
**Description**: Registered users can authenticate and access the system
**Acceptance Criteria**:
- [ ] Login form accepts email and password
- [ ] Invalid credentials show appropriate error message
- [ ] Successful login creates session/JWT token
- [ ] User is redirected to dashboard after login
- [ ] Remember me option available

#### FR-3: Password Reset
**Priority**: Should-have
**Description**: Users can reset forgotten passwords
**Acceptance Criteria**:
- [ ] Forgot password link on login page
- [ ] Email with reset link sent to user
- [ ] Reset link expires after 1 hour
- [ ] User can set new password
- [ ] Old password is invalidated

### Non-Functional Requirements

#### NFR-1: Security
- Passwords hashed using bcrypt (10+ rounds)
- JWT tokens expire after 24 hours
- Refresh tokens for extended sessions
- HTTPS required for all auth endpoints
- Protection against brute force attacks (rate limiting)
- CSRF protection implemented

#### NFR-2: Performance
- Login response time < 500ms
- Registration process < 1 second
- Token validation < 100ms

#### NFR-3: Accessibility
- Forms are keyboard navigable
- Screen reader compatible
- Error messages clearly announced
- WCAG 2.1 AA compliance

### User Stories

**US-1**: As a new user, I want to register for an account, so that I can access the platform
**US-2**: As a registered user, I want to login securely, so that I can access my data
**US-3**: As a user, I want to reset my password if I forget it, so that I can regain access

### Technical Specifications

#### Backend
- Framework: [Express/Fastify/NestJS]
- Authentication: JWT with refresh tokens
- Password hashing: bcrypt
- Rate limiting: express-rate-limit
- Validation: Zod/Joi

**API Endpoints**:

POST /api/auth/register - User registration POST /api/auth/login - User login POST /api/auth/refresh - Refresh JWT token POST /api/auth/logout - User logout POST /api/auth/forgot-password - Request password reset POST /api/auth/reset-password - Reset password with token GET /api/auth/me - Get current user

#### Frontend
- Framework: [React/Vue/Next.js]
- State management: [Context/Zustand/Redux]
- Form handling: React Hook Form
- API client: Axios/Fetch

**Components**:
- RegisterForm
- LoginForm
- ForgotPasswordForm
- ResetPasswordForm
- AuthProvider (context)

#### Database
```sql
CREATE TABLE users (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  email VARCHAR(255) UNIQUE NOT NULL,
  password_hash VARCHAR(255) NOT NULL,
  email_verified BOOLEAN DEFAULT FALSE,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

CREATE TABLE password_resets (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  user_id UUID REFERENCES users(id),
  token VARCHAR(255) UNIQUE NOT NULL,
  expires_at TIMESTAMP NOT NULL,
  used BOOLEAN DEFAULT FALSE,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

Dependencies

• bcrypt library for password hashing
• jsonwebtoken for JWT handling
• nodemailer for email sending
• express-validator for input validation

Assumptions

• Email service is already configured
• HTTPS is available in production
• Database supports UUIDs

Risks

Risk	Impact	Mitigation
Email delivery issues	High	Use reliable email service (SendGrid/AWS SES)
Token security	High	Use secure random tokens, HTTPS only
Database performance	Medium	Index email column, use connection pooling

Testing Requirements

• Unit tests for auth service methods
• Integration tests for API endpoints
• E2E tests for registration and login flows
• Security testing (SQL injection, XSS, CSRF)
• Load testing for concurrent logins

Implementation Estimate

• Backend: 3-5 days
• Frontend: 2-3 days
• Testing: 2 days
• Total: 7-10 days

### Step 5: Save and Share

Save the document to appropriate location:
```bash
mkdir -p docs/requirements
cat > docs/requirements/user-authentication.md <<EOF
[Requirements content]
EOF

Optionally create GitHub issue:

gh issue create \
  --title "Requirements: User Authentication" \
  --body "$(cat docs/requirements/user-authentication.md)" \
  --label "requirements,documentation"

Best Practices

Question Asking

• Start with open-ended questions
• Follow up with specific clarifications
• Don't assume - ask when uncertain
• Validate understanding by summarizing

Requirement Quality

• Make requirements specific and measurable
• Include clear acceptance criteria
• Use consistent terminology
• Avoid technical jargon in business requirements

Prioritization

• Use MoSCoW (Must, Should, Could, Won't)
• Distinguish MVP from future enhancements
• Consider dependencies when prioritizing

Documentation

• Use consistent formatting
• Include code examples where helpful
• Link to related documentation
• Keep language clear and concise

Integration with Other Tools

This skill works well with:

• /sng-requirements command (for manual invocation)
• requirements-analyst agent (for deep analysis)
• development-planner agent (for next step)
• GitHub issue creation workflows

Example Scenarios

Scenario 1: Vague Feature Request

User: "We need better search"
Claude: [Activates requirements-gathering skill]
- What should be searchable? (users, products, documents)
- What search features are needed? (filters, autocomplete)
- Performance requirements? (results per second)
- Analyzes current search implementation
- Documents comprehensive requirements

Scenario 2: Bug Report Needs Clarification

User: "Search is broken"
Claude: [Activates requirements-gathering skill]
- What specific search functionality is broken?
- What is the expected vs actual behavior?
- Steps to reproduce?
- Creates detailed bug report with acceptance criteria for fix

Scenario 3: New Feature from Stakeholder

User: "CEO wants a dashboard"
Claude: [Activates requirements-gathering skill]
- What data should be displayed?
- Who will use this dashboard?
- Real-time or static data?
- Mobile support needed?
- Creates comprehensive requirements with user stories

Output Format

Always provide:

1. Requirements Summary: Executive overview (2-3 sentences)
2. Structured Document: Complete requirements in markdown
3. Next Steps: Suggested actions (create issue, start planning, etc.)
4. Open Questions: Any items that still need clarification
5. File Location: Where requirements were saved

Tips

• Don't be afraid to ask "dumb" questions - better to clarify than assume
• Look for existing patterns in the codebase to maintain consistency
• Consider the full user journey, not just the happy path
• Think about error cases and edge conditions
• Include non-functional requirements (performance, security, accessibility)
• Estimate implementation effort to help with planning