Domain Expert

Overview

The Domain Expert agent brings business domain knowledge to your AI team. Unlike other agents that specialize in technical domains (frontend, backend, etc.), the Domain Expert understands your business: its terminology, rules, data models, and constraints.

Out of the box, the Domain Expert has general knowledge about common domains. But its true power comes from customization—teaching it the specifics of your industry, company, and product.

What the Domain Expert Does

Data Discovery

The Domain Expert understands your data architecture and helps other agents work with it correctly:

• Explains entity relationships and cardinality
• Identifies which data fields are sensitive or PII
• Recommends appropriate access patterns for queries
• Flags data consistency requirements across services

# Ask the Domain Expert about data models
@domain-expert Explain the relationship between Orders, LineItems, 
and Products. What are the access patterns for order history queries?

# Response includes:
# - Entity relationship diagram
# - Common query patterns with performance notes
# - Data consistency rules
# - Soft delete vs hard delete policies

Business Rules

Business logic is often implicit—living in tribal knowledge or scattered documentation. The Domain Expert centralizes this knowledge:

• Validation rules (what makes an order valid?)
• State transitions (order lifecycle, approval workflows)
• Calculation rules (pricing, discounts, taxes)
• Compliance requirements (GDPR, HIPAA, PCI-DSS)

# Query business rules
@domain-expert What are the rules for order cancellation?
Include: time limits, refund policies, inventory implications.

# Response includes:
# - Cancellation window (24 hours for standard, none for custom)
# - Refund calculation (full if unshipped, minus restocking if shipped)
# - Inventory restoration logic
# - Notification requirements

Domain Knowledge

The Domain Expert provides context that other agents need to make correct decisions:

• Industry-specific terminology and abbreviations
• Regulatory constraints that affect implementation
• Integration requirements with industry systems
• Common user workflows and expectations

When to Engage

How to Customize

Customize the Domain Expert by adding documentation to agent_docs/. The Domain Expert automatically incorporates this context.

Configuration Location

agent_docs/
├── domain/
│   ├── glossary.md           # Terminology definitions
│   ├── data-models.md        # Entity relationships
│   ├── business-rules.md     # Validation and workflows
│   ├── compliance.md         # Regulatory requirements
│   └── integrations.md       # External systems
├── context.md                # Project overview
└── conventions.md            # Coding standards

Glossary Template

# Domain Glossary

## Core Entities

### Customer
A registered user who can place orders. NOT the same as "user" 
(which includes admin staff).

### Order
A confirmed purchase. Orders are immutable after confirmation.
Use "cart" for unconfirmed purchases.

### SKU (Stock Keeping Unit)
Unique identifier for a purchasable item variant. 
Format: {category}-{product}-{variant}
Example: ELEC-PHONE-BLK-128GB

## Business Terms

### MRR (Monthly Recurring Revenue)
Sum of all active subscription amounts, normalized to monthly.
Excludes one-time purchases and trial accounts.

### Churn
Customer cancellation within 30 days of charge.
Trial expirations are NOT counted as churn.

Business Rules Template

# Business Rules

## Order Processing

### Order Validation
- Minimum order value: $10 (waived for subscription renewals)
- Maximum items per order: 100
- Shipping address must match billing country for international

### Pricing Rules
- Discounts apply before tax
- Tax calculated based on shipping address (not billing)
- Maximum discount: 50% (requires manager approval above this)

### Inventory
- Reserve inventory at cart addition, not checkout
- Reservation timeout: 30 minutes
- Overselling allowed for preorders only

## Refunds

### Refund Windows
| Product Type | Window | Method |
|-------------|--------|--------|
| Physical | 30 days | Original payment |
| Digital | 7 days | Store credit only |
| Subscription | Prorated | Original payment |

Data Models Template

# Data Models

## Entity Relationships

```
Customer (1) ──── (n) Order
    │                  │
    │                  └── (n) LineItem (n) ── (1) Product
    │
    └── (1) Address (n) ───┘

Product (1) ── (n) Variant (1) ── (1) Inventory
```

## Key Fields

### Customer
- id: UUID (primary)
- email: UNIQUE, case-insensitive
- status: enum [active, suspended, deleted]
- created_at: timestamp with timezone

### Order
- id: UUID (primary)
- customer_id: FK to Customer
- status: enum [pending, confirmed, shipped, delivered, cancelled]
- total: decimal(10,2) - includes tax
- currency: ISO 4217 code

## Access Patterns

### Common Queries
- Orders by customer: indexed on customer_id
- Recent orders: indexed on created_at DESC
- Orders by status: indexed on (status, created_at)

### Performance Notes
- Order history limited to 100 by default (paginated)
- Use cursor pagination for large datasets

Example Customizations

Fintech Domain

# agent_docs/domain/fintech.md

## Regulatory Context
- PCI-DSS Level 1 compliant
- SOC 2 Type II certified
- GDPR data residency: EU customers in eu-west-1

## Financial Rules
- All amounts stored in cents (integer)
- Display currency determined by user locale
- Exchange rates cached for 1 hour max
- Settlement delay: 2 business days

## Compliance Checks
- KYC required for transactions > $3000
- AML screening on all new accounts
- Transaction monitoring for patterns

## Terminology
- "Balance" = available funds (not pending)
- "Ledger" = immutable transaction log
- "Settlement" = funds available for withdrawal

Healthcare Domain

# agent_docs/domain/healthcare.md

## Regulatory Context
- HIPAA compliant
- PHI handling requirements
- Audit logging mandatory

## Data Classification
- PHI fields: name, DOB, SSN, medical_record_number
- De-identified data: aggregated stats only
- Minimum necessary principle applies

## Access Control
- Role-based access to patient records
- Break-glass procedure for emergencies
- All access logged with reason codes

## Terminology
- "Patient" (not customer/user)
- "Encounter" (not visit/appointment)
- "Provider" (not doctor/clinician)
- "Facility" (not hospital/clinic)

E-commerce Domain

# agent_docs/domain/ecommerce.md

## Business Model
- Multi-vendor marketplace
- Commission: 15% per sale
- Vendor payout: weekly on Fridays

## Inventory Model
- Vendor-managed inventory
- Dropshipping supported
- Backorder allowed with customer consent

## Pricing Rules
- Vendor sets base price
- Platform sets maximum markup (30%)
- Dynamic pricing for flash sales
- Price match guarantee: 7 days

## Shipping
- Vendor ships directly
- Platform provides labels
- Free shipping threshold: $50
- Combined shipping for multi-vendor orders

Integration with Other Agents

The Domain Expert works alongside other agents, providing context they need to make correct decisions:

Domain Expert + Product Manager

# PM asks Domain Expert before writing requirements
@domain-expert What are the business rules for subscription upgrades?
I need to write requirements for a plan upgrade feature.

# Domain Expert provides:
# - Current upgrade paths allowed
# - Proration calculation rules
# - Billing cycle handling
# - Grandfathering policies

# PM then writes informed requirements
@product-manager Create requirements for subscription upgrades
based on the domain rules. Include edge cases for mid-cycle changes.

Domain Expert + Backend Engineer

# Backend asks Domain Expert about validation
@domain-expert What validation rules apply to the shipping address
for international orders?

# Domain Expert provides:
# - Country-specific field requirements
# - Postal code format validation
# - Restricted countries list
# - Duties/tax implications

# Backend implements with full context
@backend-engineer Implement shipping address validation
using the domain rules provided. Include country-specific formats.

Domain Expert + QA

# QA asks Domain Expert about edge cases
@domain-expert What are the edge cases for order cancellation
from a business perspective?

# Domain Expert provides:
# - Partially shipped orders
# - Orders with applied gift cards
# - Subscription orders mid-cycle
# - Orders with pending refunds

# QA creates comprehensive tests
@qa-backend Create cancellation tests covering all domain edge cases.
Include the gift card and partial shipment scenarios.

Maintaining Domain Knowledge

Knowledge Refresh Workflow

# Quarterly domain knowledge review
1. Product/Business team reviews agent_docs/domain/
2. Mark outdated sections
3. Update with current rules
4. Add new terminology and rules
5. Remove deprecated content
6. Test Domain Expert responses

# After major business changes
1. Immediately update affected rules
2. Note the change date and reason
3. Consider backward compatibility
4. Update related test expectations

Validation Checklist

# Test your Domain Expert configuration
@domain-expert Answer these validation questions:

1. What is a [key entity]? (Test glossary)
2. What are the rules for [common process]? (Test business rules)
3. How does [entity A] relate to [entity B]? (Test data models)
4. What compliance requirements affect [feature]? (Test regulatory)

# If answers are incorrect or incomplete:
# → Update the corresponding documentation
# → Re-test until accurate