# Domain Research Playbook

> **Web research is the #1 quality differentiator.**
> An analysis WITHOUT research is a 2/10 regardless of structural quality.
> An analysis WITH multi-level research can be 8-10/10.
> This step takes 2-5 minutes per application and dramatically improves analysis quality.

## MANDATORY — BLOCKING

Web research is **MANDATORY and BLOCKING**. This is NOT optional.

If WebSearch tool is unavailable:
1. Display WARNING to user: "WebSearch indisponible. Qualite d'analyse degradee."
2. AskUserQuestion: "Continuer sans recherche web ? (Non recommande — qualite 4/10 max)"
3. IF user declines → STOP and recommend fixing WebSearch availability
4. IF user confirms → proceed with `{domain_research}.source = "built-in-only"`
   and flag EVERY module with `qualityFlag: "no-web-research"`
   → Load `references/module-completeness-challenge.md` as primary fallback data source

---

## Level 1 : Recherche par APPLICATION (step-01 cadrage)

> **WHEN:** During step-01 Phase 1 (ECOUTE), BEFORE engaging the client.
> **WHO:** For EACH candidate application in a multi-app project, or the single app.

For EACH application:

### 1a. Module Discovery Search (MANDATORY)

```
Query: "{app_type} application modules features complete list"
```

Examples:
- "billing invoicing application modules features complete list ERP"
- "HR human resources application modules features complete list"
- "CRM application modules features complete list"
- "project management application modules features complete list"

**EXTRACT:**
- Standard modules for this app type
- Which are CORE (always present) vs STANDARD vs OPTIONAL
- Common module names and their scope
- Module dependencies

### 1b. Competitive Research (MANDATORY)

```
Query: "best {app_type} software features comparison"
```

Examples:
- "best invoicing software features comparison 2025"
- "best HR software absence management features"
- "best CRM software features comparison"
- "best project management software features"

**EXTRACT:**
- What do real commercial products offer? (BambooHR, Sage, Salesforce, etc.)
- Common features users expect as baseline
- Differentiating features that add value
- Features that are table stakes vs nice-to-have

### 1c. Data Model Research (1 per app)

```
Query: "{app_type} data model entities relationships best practices"
```

**EXTRACT:**
- Standard entities and their relationships
- Common anti-patterns to avoid (e.g., "storing salary on Employee instead of salary history table")
- Industry-standard naming and cardinality

### Storage Format

```yaml
{domain_research}.applications[{app_code}]:
  standardModules:
    - name: "Invoices"
      classification: "CORE"  # CORE | STANDARD | OPTIONAL
      description: "Invoice lifecycle management"
      standardSections: ["list", "detail", "generate", "dashboard"]
    - name: "CreditNotes"
      classification: "CORE"
      description: "Legally required for invoice corrections/cancellations"
      standardSections: ["list", "detail"]
  competitiveInsights:
    - product: "Sage"
      keyFeatures: ["auto-numbering", "multi-currency", "credit notes", "recurring invoices"]
    - product: "Stripe Invoicing"
      keyFeatures: ["payment tracking", "dunning", "tax calculation"]
  dataModel:
    entities: ["Invoice", "InvoiceLine", "CreditNote", "Payment", "PaymentTerm"]
    relationships: ["Invoice → Client (N:1)", "Invoice → InvoiceLine (1:N)"]
    antiPatterns: ["single invoice entity without credit notes"]
```

---

## Level 2 : Recherche par MODULE (step-03 specify)

> **WHEN:** During step-03 section A-bis, BEFORE entity specification.
> **WHO:** For EACH module with >= 2 entities. SKIP: Portal, pure config modules.

For EACH module:

### 2a. Section/UX Research (MANDATORY)

```
Query: "{module_domain} management system features screens views UX"
```

Examples:
- "absence management system features screens views"
- "invoice management application features views UX"
- "CRM opportunity pipeline features screens"

**EXTRACT:**
- Standard sections/views (list, detail, calendar, kanban, etc.)
- **Contextual filtered views** — this is CRITICAL:
  - Workflow modules: open-requests, rejected, history, my-{entity}
  - Data modules: by-status, by-period, by-category
- Dashboard/reporting expectations
- Standard UX patterns (approval queue, batch actions, etc.)

### 2b. Business Rules Research (MANDATORY for workflow modules)

```
Query: "{module_domain} business rules validation constraints best practices"
```

Examples:
- "absence leave management business rules HR constraints"
- "invoice billing business rules validation constraints"
- "CRM opportunity management business rules"

**EXTRACT:**
- **Domain-specific validation rules** (NOT just "date must be valid"):
  - Half-day absences, notice periods, capacity limits
  - Invoice sequential numbering, credit note linking
  - Opportunity probability rules, stage-gate validation
- Calculation rules with formulas
- Workflow constraints and edge cases
- Regulatory/compliance requirements

### 2c. Entity Design Research (1 per complex entity, OPTIONAL)

```
Query: "{entity_name} entity design pattern ERP best practices"
```

**EXTRACT:**
- Standard attributes for this entity type
- Versioned vs. inline data patterns (e.g., salary history)
- Common relationships and cardinality
- Known anti-patterns

### Storage Format

```yaml
{domain_research}.modules[{module_code}]:
  sections:
    standard: ["list", "detail", "approve", "calendar"]
    contextualViews: ["open-requests", "rejected", "history", "my-balance"]
    dashboard: ["absence-kpi", "team-calendar"]
  businessRules:
    domainSpecific:
      - "Half-day absences (morning/afternoon)"
      - "Minimum 48h notice for planned leave"
      - "Max 30% of team absent simultaneously"
      - "Carry-over days expire after March 31"
      - "Medical certificate for absences > 3 days"
    regulatory:
      - "Minimum 25 days paid leave per year (France)"
  entityPatterns:
    Absence:
      standardAttributes: ["employeeId", "typeId", "startDate", "endDate", "duration", "status", "halfDay"]
      versionedData: []
      workflowStates: ["Draft", "Submitted", "Approved", "Rejected", "Cancelled"]
```

---

## Level 3 : Recherche reglementaire (si applicable)

> **WHEN:** During step-01 for applicable domains, alongside Level 1 research.
> **WHO:** Billing/Finance, HR, any domain with legal requirements.

### For Billing/Finance domains:
```
Query: "{country} invoice legal requirements numbering format"
```

**EXTRACT:** Sequential numbering, immutability of sent invoices, retention period, credit note requirements, VAT rules.

### For HR domains:
```
Query: "{country} absence leave legal requirements types"
```

**EXTRACT:** Mandatory leave types, minimum days, carry-over rules, medical certificate requirements.

Store in: `{domain_research}.regulatory[]`

---

## Search Budget

| Project Type | Level 1 (per app) | Level 2 (per module) | Level 3 | Total |
|---|---|---|---|---|
| Single-app, 1-3 modules | 3 searches | 2/module = 4-6 | 0-2 | **7-11** |
| Single-app, 4-6 modules | 3 searches | 2/module = 8-12 | 0-2 | **11-17** |
| Multi-app (4 apps, ~10 modules) | 3/app = 12 | 2/module = 16-20 | 0-4 | **28-36** |

> **Token impact:** Each search returns ~500-1000 tokens. Total for a 4-app project: ~15K-30K tokens.
> This is a small price for dramatically improved analysis quality.

---

## Critical Notes

> **CRITICAL:** This research is INTERNAL context. Do NOT show raw search results to the client.
> Use the findings to:
> - **Challenge scope completeness** — flag CORE modules the user didn't mention
> - **Ground entity architecture** — use real-world data models, not guesswork
> - **Propose domain-specific business rules** — go beyond generic CRUD validation
> - **Anticipate contextual views** — workflow modules need filtered views
> - **Inform proactive suggestions** — "standard billing also includes credit notes because..."
> - **Prevent common anti-patterns** — catch mistakes before they become architecture

> **NEVER use research as an excuse to skip user validation.**
> Research INFORMS your proposals. The user VALIDATES them.
