Extract Requirements Workflow

Purpose

Systematic process for extracting business requirements from undocumented or poorly documented codebases.

When to Use

• ✅ Legacy system with no documentation

• ✅ Planning migration (need requirements baseline)

• ✅ M&A due diligence (understand acquired system)

• ✅ Compliance audit (document what system does)

• ✅ Knowledge transfer (developers leaving)

Prerequisites

Codebase Indexed

codecompass batch:index <path>

Infrastructure Running

codecompass health

Extraction Workflow

Phase 1: Automated Extraction

Step 1.1: Run Requirements Extractor

codecompass requirements:extract --project-id <id> --output requirements.md

What this extracts:

• Validation Rules → Business constraints

• Controller Actions → Use cases

• Database Constraints → Data integrity rules

• RBAC/Authorization → Access requirements

• Business Logic → Domain rules

Step 1.2: Review Output Check generated requirements.md :

• Completeness (coverage of major features)

• Accuracy (rules match actual behavior)

• Gaps (missing business logic)

Phase 2: Validation Rule Analysis

From Models/Entities:

// Yii2 Model example public function rules() { return [ [['email', 'password'], 'required'], ['email', 'email'], ['password', 'string', 'min' => 8], ['age', 'integer', 'min' => 18], ]; }

Extracted Requirements:

User Registration Requirements

• REQ-001: Email address is mandatory
• REQ-002: Email must be valid format
• REQ-003: Password is mandatory
• REQ-004: Password minimum length: 8 characters
• REQ-005: User must be at least 18 years old

Phase 3: Use Case Extraction

From Controllers:

// Controller actions → Use cases public function actionCreate() { // Use Case: Create New Order }

public function actionApprove($id) { // Use Case: Approve Order (with authorization check) }

public function actionCancel($id) { // Use Case: Cancel Order (business rules apply) }

Extracted Use Cases:

Order Management Use Cases

UC-001: Create New Order

Actor: Customer Preconditions: User authenticated Steps:

1. User selects products
2. System validates inventory
3. User provides shipping address
4. System calculates total
5. Order created in pending status

UC-002: Approve Order

Actor: Manager Preconditions:

• Order in pending status
• User has 'manager' role Steps:

1. Manager reviews order details
2. System validates business rules
3. Order status changed to approved
4. Notification sent to customer

Phase 4: Business Rule Discovery

Semantic Search for Rules:

codecompass search:semantic "business validation rules for order approval" codecompass search:semantic "conditions for discount calculation" codecompass search:semantic "authorization checks for admin actions"

Common Patterns to Find:

• Conditional Logic → Business rules

• Status Transitions → Workflow states

• Calculations → Business formulas

• Validations → Constraints

• Authorization Checks → Access rules

Phase 5: Data Model Requirements

From Database Schema:

CREATE TABLE orders ( id INT PRIMARY KEY, status ENUM('pending', 'approved', 'shipped', 'cancelled'), total DECIMAL(10,2) NOT NULL CHECK (total >= 0), customer_id INT NOT NULL FOREIGN KEY REFERENCES customers(id), created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP );

Extracted Requirements:

Data Requirements

• REQ-010: Order must have unique identifier
• REQ-011: Order status: pending, approved, shipped, or cancelled
• REQ-012: Order total must be non-negative
• REQ-013: Order must be associated with a customer
• REQ-014: Order creation timestamp must be recorded

Phase 6: Workflow Mapping

Identify State Machines:

Order Status Flow: pending → approved → shipped → delivered ↓ cancelled

Extract Transitions:

Order Workflow

States: pending, approved, shipped, cancelled, delivered

Transitions:

• pending → approved (requires: manager approval)
• approved → shipped (requires: items in stock)
• shipped → delivered (requires: delivery confirmation)
• pending|approved → cancelled (requires: cancellation reason)

Business Rules:

• Cannot cancel after shipped
• Cannot approve if out of stock
• Refund required if cancelled after payment

Extraction Techniques

Technique 1: Code Reading Patterns

Look for:

• if statements → Business conditions

• switch/case → State transitions

• Loops → Bulk operations

• Exceptions → Error handling requirements

• Comments → Intent (when present)

Technique 2: Test Analysis

Tests reveal:

• Expected behavior (what should happen)

• Edge cases (what shouldn't happen)

• Valid input ranges

• Error scenarios

codecompass search:semantic "test cases for order validation"

Technique 3: Configuration Analysis

Config files contain:

• Feature flags → Optional requirements

• Limits/thresholds → Business constraints

• Integration settings → External dependencies

Technique 4: Semantic Clustering

Find related code:

Find all code related to "discount calculation"

codecompass search:semantic "discount calculation logic"

Find all code related to "inventory management"

codecompass search:semantic "inventory stock management"

Group results by business capability

Output Formats

Format 1: Requirements Document (Markdown)

Business Requirements - [System Name]

Functional Requirements

FR-001: User Authentication

Priority: High Description: System must authenticate users via email and password Acceptance Criteria:

• Email validation follows RFC 5322
• Password minimum 8 characters
• Account locked after 5 failed attempts Source: UserController::actionLogin(), User::validatePassword()

FR-002: Order Approval Workflow

...

Format 2: Capability Map (Structured)

{ "capabilities": { "user_management": { "features": ["register", "login", "reset_password"], "rules": ["email_unique", "password_complexity"], "roles": ["user", "admin"] }, "order_processing": { "features": ["create", "approve", "cancel", "ship"], "rules": ["approval_required", "inventory_check"], "workflow": "pending→approved→shipped→delivered" } } }

Format 3: Use Case Catalog

Validation Steps

Step 1: Cross-Check with Tests

Compare extracted requirements with test cases:

• Tests validate requirements

• Missing tests → Undocumented behavior

• Failing tests → Requirements changed

Step 2: Semantic Verification

For each requirement, verify in code

codecompass search:semantic "password must be at least 8 characters"

Should find validator implementation

Step 3: Interview Stakeholders (if available)

• Validate extracted requirements

• Fill gaps in documentation

• Clarify ambiguous logic

Step 4: Traceability Matrix

Map requirements to code:

Common Patterns

Pattern 1: Implicit Requirements

Code:

if ($order->total < 1000) { // No approval needed }

Requirement:

REQ: Orders under $1000 do not require manager approval

Pattern 2: Embedded Business Logic

Code:

$discount = ($customer->vip) ? 0.20 : 0.10;

Requirement:

REQ: VIP customers receive 20% discount, regular customers 10%

Pattern 3: Temporal Constraints

Code:

if (strtotime($order->created_at) > strtotime('-30 days')) { // Can cancel }

Requirement:

REQ: Orders can only be cancelled within 30 days of creation

Best Practices

✅ Do

• Extract from multiple sources (code, tests, configs)

• Use semantic search for concept discovery

• Validate with tests

• Document sources for traceability

• Prioritize by business impact

• Include non-functional requirements (performance, security)

❌ Don't

• Rely solely on comments (often outdated)

• Assume standard behavior without verification

• Skip edge cases

• Ignore error handling logic

• Document technical implementation instead of business requirements

Related Skills

• 0-discover-capabilities.md

• Find relevant modules

• semantic-search.md

• Search for business logic

• analyze-yii2-project.md

• Framework-specific extraction

Related Modules

From .ai/capabilities.json :

• requirements

• RequirementsExtractionService

• business-analyzer

• CapabilityCatalogService

• search

• Semantic code search

• analyzers

• Code analysis for extraction

Remember: Requirements are what the system must do, not how it does it. Focus on business value, not technical implementation.