requirements-extractor

Purpose

The requirements-extractor skill provides structured methods for parsing GitHub issues to extract and organize requirements information. It ensures that all requirements are properly identified, categorized, and documented in a format suitable for downstream design and implementation phases.

When to Use

This skill auto-activates when you:

• Analyze GitHub issues for requirements
• Parse feature requests or bug reports
• Extract acceptance criteria from issue descriptions
• Identify user stories (As a... I want... So that...)
• Distinguish functional from non-functional requirements
• Clarify ambiguous or missing requirements

Provided Capabilities

1. Requirement Identification

• Functional Requirements: What the system must do
• Non-Functional Requirements: Quality attributes (performance, security, usability, scalability)
• Business Requirements: Business goals and objectives
• User Requirements: User-facing capabilities
• System Requirements: Technical system capabilities

2. Acceptance Criteria Extraction

• Parse acceptance criteria from issue body
• Identify testable conditions
• Convert narratives to checkable criteria
• Flag missing or ambiguous criteria

3. User Story Parsing

• Identify user story format: "As a [role], I want [feature], so that [benefit]"
• Extract role, feature, and benefit components
• Parse epic stories vs. individual stories
• Link related stories

4. Requirement Categorization

• Must Have (P0): Critical for MVP
• Should Have (P1): Important but not critical
• Could Have (P2): Desirable but optional
• Won't Have (P3): Out of scope for this release

5. Requirement Validation

• Check for completeness using requirements-checklist.md
• Identify ambiguous language
• Flag conflicting requirements
• Ensure testability

Usage Guide

Step 1: Fetch Issue Content

gh issue view <issue-number> --json title,body,labels,comments --repo matteocervelli/llms

Step 2: Parse Issue Structure

Look for these patterns in issue body:

Functional Requirements Indicators:

• "The system must..."
• "The feature should..."
• "Users can..."
• "When X happens, then Y..."

Non-Functional Requirements Indicators:

• "Response time..."
• "Must handle N concurrent users..."
• "Should be accessible to..."
• "Must comply with..."
• "Performance target..."

Acceptance Criteria Indicators:

• "Acceptance Criteria:"
• "Definition of Done:"
• Checklist items: - [ ]
• "Given... When... Then..." (BDD format)

User Stories Indicators:

• "As a..."
• "User persona..."
• "Use case..."

Step 3: Extract Functional Requirements

Parse statements that describe what the system does:

### Functional Requirements
1. **[FR-001]** User Authentication: System must authenticate users via email/password
2. **[FR-002]** Data Export: Users can export data to CSV, JSON, or PDF formats
3. **[FR-003]** Real-time Updates: System must push updates to clients within 5 seconds

Naming Convention: FR-XXX for functional requirements

Step 4: Extract Non-Functional Requirements

Parse quality attributes:

### Non-Functional Requirements

#### Performance
- **[NFR-P-001]** API response time must be < 200ms for 95th percentile
- **[NFR-P-002]** System must handle 1000 concurrent users

#### Security
- **[NFR-S-001]** All data transmission must use TLS 1.3+
- **[NFR-S-002]** Passwords must be hashed with bcrypt (cost factor ≥12)

#### Usability
- **[NFR-U-001]** UI must be WCAG 2.1 Level AA compliant
- **[NFR-U-002]** All actions must be reversible within 30 seconds

#### Scalability
- **[NFR-SC-001]** Architecture must support horizontal scaling
- **[NFR-SC-002]** Database must handle 10M+ records without degradation

Naming Convention: NFR-[Category]-XXX

Step 5: Extract Acceptance Criteria

Convert issue acceptance criteria to structured format:

### Acceptance Criteria

- [ ] **AC-001**: User can log in with valid credentials
  - Given valid email and password
  - When user submits login form
  - Then user is redirected to dashboard
  - And session token is created

- [ ] **AC-002**: Invalid login shows error message
  - Given invalid credentials
  - When user submits login form
  - Then error message displays: "Invalid email or password"
  - And user remains on login page
  - And login attempt is logged

- [ ] **AC-003**: Forgot password link is visible
  - Given user is on login page
  - When user views page
  - Then "Forgot Password?" link is visible
  - And link navigates to password reset flow

Naming Convention: AC-XXX for acceptance criteria

Step 6: Parse User Stories

Extract user stories in standard format:

### User Stories

**Story 1**: User Login
- **As a** registered user
- **I want to** log in with my email and password
- **So that** I can access my personalized dashboard
- **Priority**: Must Have (P0)
- **Acceptance Criteria**: AC-001, AC-002, AC-003

**Story 2**: Guest Browsing
- **As a** guest visitor
- **I want to** browse public content without logging in
- **So that** I can evaluate the platform before registering
- **Priority**: Should Have (P1)
- **Acceptance Criteria**: AC-004, AC-005

Step 7: Categorize by Priority

Use MoSCoW method:

### Requirement Priorities

#### Must Have (P0) - Critical for MVP
- FR-001: User Authentication
- FR-003: Real-time Updates
- NFR-S-001: TLS encryption

#### Should Have (P1) - Important
- FR-002: Data Export
- NFR-U-001: WCAG compliance

#### Could Have (P2) - Desirable
- FR-005: Dark mode support
- NFR-P-003: CDN integration

#### Won't Have (P3) - Out of scope
- FR-010: AI-powered recommendations (future release)

Step 8: Validate Using Checklist

Use requirements-checklist.md to validate each requirement:

# Check against requirements checklist
# Manually verify each criterion from requirements-checklist.md

Validation Criteria:

• ✅ Clear and unambiguous
• ✅ Testable
• ✅ Complete
• ✅ Consistent (no conflicts)
• ✅ Traceable to business goals
• ✅ Feasible with available resources

Step 9: Flag Issues

Identify and document:

### Requirement Issues

**Ambiguous Requirements**:
- FR-007: "System should be fast" → Needs quantification (What is "fast"?)
- FR-012: "Easy to use" → Needs specific usability criteria

**Missing Requirements**:
- No error handling requirements specified for API failures
- Logging and monitoring requirements not defined
- Backup and recovery procedures not mentioned

**Conflicting Requirements**:
- FR-015 requires real-time sync, but NFR-P-005 sets 5-minute update interval

Best Practices

1. Be Thorough

• Read entire issue including comments
• Check linked issues and PRs
• Review labels and milestones
• Look for implicit requirements

2. Use Standard Formats

• Consistent naming conventions
• Structured templates
• Clear categorization
• Numbered identifiers

3. Validate Completeness

• Every requirement has ID
• Every requirement is testable
• Every requirement has priority
• Every requirement traces to business goal

4. Handle Ambiguity

• Flag vague language
• Request clarification
• Document assumptions
• Provide examples

5. Consider Non-Obvious Requirements

• Error handling
• Logging and monitoring
• Performance under load
• Data migration needs
• Backward compatibility
• Accessibility
• Internationalization
• Privacy and compliance

Resources

requirements-checklist.md

Comprehensive checklist for validating requirements including:

• Completeness criteria
• Clarity criteria
• Consistency checks
• Testability validation
• Feasibility assessment

extraction-patterns.md

Common patterns for identifying requirements in natural language:

• Keywords and phrases
• Sentence structures
• Issue templates
• Standard formats (BDD, user stories)

Example Usage

Input (GitHub Issue)

Title: Add user authentication feature

Description:
As a user, I want to log in with my email and password so that I can access my personal data.

The system should support:
- Email/password login
- "Remember me" option
- Forgot password flow
- Account lockout after 5 failed attempts

Acceptance Criteria:
- [ ] User can log in with valid credentials
- [ ] Invalid login shows error message
- [ ] Password reset email sent within 1 minute
- [ ] Locked accounts show appropriate message

Output (Extracted Requirements)

## Requirements

### Functional Requirements
1. **[FR-001]** Email/Password Authentication: System must authenticate users via email and password
2. **[FR-002]** Remember Me: System must provide "remember me" checkbox to maintain session
3. **[FR-003]** Password Reset: System must send password reset email when user requests
4. **[FR-004]** Account Lockout: System must lock account after 5 consecutive failed login attempts

### Non-Functional Requirements

#### Security
- **[NFR-S-001]** Password storage must use bcrypt hashing
- **[NFR-S-002]** Session tokens must expire after 24 hours (unless "remember me")
- **[NFR-S-003]** Login attempts must be rate-limited (max 10/hour per IP)

#### Performance
- **[NFR-P-001]** Password reset email must be sent within 1 minute
- **[NFR-P-002]** Login response time must be < 500ms

#### Usability
- **[NFR-U-001]** Error messages must not reveal whether email exists
- **[NFR-U-002]** Locked account message must provide unlock instructions

### Acceptance Criteria
- [ ] **AC-001**: User can log in with valid email/password
- [ ] **AC-002**: Invalid login shows generic error message
- [ ] **AC-003**: Password reset email sent within 1 minute of request
- [ ] **AC-004**: Account locked after 5 failed attempts with clear message
- [ ] **AC-005**: "Remember me" extends session to 30 days

### User Stories
**Story 1**: User Login
- **As a** registered user
- **I want to** log in with email and password
- **So that** I can access my personal data
- **Priority**: Must Have (P0)

Integration

This skill is used by:

• analysis-specialist agent during Phase 1: Requirements Analysis
• Activates automatically when agent analyzes GitHub issues
• Provides structured output for analysis document generation

---

Version: 2.0.0 Auto-Activation: Yes (when extracting requirements) Phase: 1 (Requirements Analysis) Created: 2025-10-29