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