---
name: extract-business-rules
description: Extract business rules (BR-*) from requirements - validation rules, business logic, error handling, and decision criteria. Use when disambiguating requirements to identify specific rules that can be autogenerated into validators and logic.
allowed-tools: [Read, Write, Edit]
---

# extract-business-rules

**Skill Type**: Actuator (Requirements Disambiguation)
**Purpose**: Extract BR-* business rules from REQ-* requirements
**Prerequisites**: REQ-* requirement exists

---

## Agent Instructions

You are extracting **business rules** (BR-*) from requirements.

**Business rules** are:
- Validation rules (format, range, enum)
- Business logic (decisions, calculations, state machines)
- Error handling (what errors, what messages)
- Acceptance rules (what makes data valid/invalid)

**Goal**: Identify rules precise enough for code autogeneration.

---

## BR-* Categories

### 1. Validation Rules

**Format validation**:
```yaml
BR-001: Email validation
  - Format: regex ^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$
  - Error: "Invalid email format"
  - Autogenerate: validate_email(email) -> Optional[str]
```

**Range validation**:
```yaml
BR-010: Age validation
  - Minimum: 18
  - Maximum: 120
  - Error: "Age must be between 18 and 120"
  - Autogenerate: validate_age(age) -> Optional[str]
```

**Enum validation**:
```yaml
BR-020: Card type validation
  - Allowed: ["Visa", "Mastercard", "Amex"]
  - Error: "Card type not supported"
  - Autogenerate: validate_card_type(type) -> Optional[str]
```

---

### 2. Business Logic Rules

**State machines**:
```yaml
BR-030: Account lockout logic
  - Max attempts: 3
  - Lockout duration: 15 minutes
  - Reset on success: Yes
  - States: active, locked, expired
  - Autogenerate: LockoutStateMachine class
```

**Decision rules**:
```yaml
BR-040: Refund eligibility
  - Condition: purchase_date within 30 days AND product not digital
  - Result: eligible or not_eligible
  - Error: "Refunds only available within 30 days for physical products"
  - Autogenerate: is_refund_eligible() -> bool
```

---

### 3. Error Handling Rules

```yaml
BR-050: Error message format
  - Template: "{field} {error_type}. {help_text}"
  - Example: "Email invalid email format. Use format: user@example.com"
  - Autogenerate: format_error_message() function
```

---

### 4. Data Transformation Rules

```yaml
BR-060: Email normalization
  - Transform: Convert to lowercase
  - Trim: Remove leading/trailing whitespace
  - Validate: After transformation
  - Autogenerate: normalize_email(email) -> str
```

---

## Extraction Process

### Step 1: Parse Requirement

Read requirement and identify rule candidates:
- Look for: "must", "should", "required", "only", "between", "minimum", "maximum"
- Look for: formats, patterns, ranges, lists
- Look for: error messages, validation criteria

---

### Step 2: Create BR-* Specifications

**Template**:
```yaml
BR-{ID}: {Rule Name}
  - Description: {What this rule does}
  - Specification: {Precise spec - regex, range, formula}
  - Error Message: "{User-facing error message}"
  - Autogenerate: {Yes/No - can code be auto-generated?}
  - Dependencies: {Other BR-* this depends on}
```

**Example**:
```yaml
BR-001: Email validation
  - Description: Validate email address format
  - Specification: regex ^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$
  - Error Message: "Invalid email format"
  - Autogenerate: Yes
  - Dependencies: None

BR-002: Password length validation
  - Description: Ensure password meets minimum length
  - Specification: len(password) >= 12
  - Error Message: "Password must be at least 12 characters"
  - Autogenerate: Yes
  - Dependencies: None

BR-003: Password complexity validation
  - Description: Ensure password has required character types
  - Specification:
      has_uppercase: password contains [A-Z]
      has_lowercase: password contains [a-Z]
      has_number: password contains [0-9]
      has_special: password contains [!@#$%^&*]
  - Error Message: "Password must contain uppercase, lowercase, number, and special character"
  - Autogenerate: Yes
  - Dependencies: BR-002 (length must be checked first)
```

---

### Step 3: Number BR-* Sequentially

**Rules**:
- Start at BR-001
- Sequential within requirement
- Gaps OK if BR deleted later

**Example**:
```
<REQ-ID>:
  - BR-001: Email validation
  - BR-002: Password length
  - BR-003: Password complexity
  - BR-004: Email case handling
  - BR-005: Account lockout
```

---

## Output Format

```
[EXTRACT BUSINESS RULES - <REQ-ID>]

Requirement: User login with email and password

Business Rules Extracted:

Validation Rules (4):
  ✓ BR-001: Email validation (regex pattern)
  ✓ BR-002: Password minimum length (12 chars)
  ✓ BR-003: Password complexity (uppercase, lowercase, number, special)
  ✓ BR-004: Email case sensitivity (lowercase normalization)

Business Logic (1):
  ✓ BR-005: Account lockout (3 attempts, 15min duration)

Total: 5 business rules

Autogeneration Ready:
  ✓ BR-001 → validate_email()
  ✓ BR-002 → validate_password_length()
  ✓ BR-003 → validate_password_complexity()
  ✓ BR-004 → normalize_email()
  ✓ BR-005 → LockoutTracker class

Updated: docs/requirements/authentication.md
  Added: Business Rules section with 5 BR-*

✅ Business Rules Extraction Complete!
```

---

## Notes

**Good BR-* characteristics**:
- **Specific**: No ambiguity (regex, not "valid format")
- **Testable**: Can write test to verify
- **Autogenerable**: Can generate code from spec
- **Independent**: Each BR-* is self-contained

**BR-* vs Requirements**:
```
Requirement (REQ-*): High-level capability
  "User can log in with email and password"

Business Rules (BR-*): Low-level specifications
  BR-001: Email regex pattern
  BR-002: Password min 12 chars
  BR-003: Lockout after 3 attempts
```

**Homeostasis Goal**:
```yaml
desired_state:
  all_requirements_have_business_rules: true
  all_br_autogenerable: true
```

**"Excellence or nothing"** 🔥