# Error Handling & Fallback Strategies

> **⚠️ IMPORTANT: When search returns no results or insufficient results, follow these fallback strategies.**

## Step 2.5: Handle Search Failures

If search returns **0 results** or results are **not relevant**, follow this fallback sequence:

### Fallback Strategy 1: Try Broader Keywords

```bash
# Original query: "电梯设备状态面板"
# If no results, try broader terms:
python3 <skill-path>/designing-tke-frontends/scripts/search.py "设备 状态" --domain component
python3 <skill-path>/designing-tke-frontends/scripts/search.py "状态 面板" --domain layout
python3 <skill-path>/designing-tke-frontends/scripts/search.py "card status" --domain component
```

**Action:** Remove specific terms, try more general keywords.

### Fallback Strategy 2: Try Other Domains

```bash
# If component domain returns nothing, try layout:
python3 <skill-path>/designing-tke-frontends/scripts/search.py "设备状态" --domain layout
# Or use auto-fallback (enabled by default):
python3 <skill-path>/designing-tke-frontends/scripts/search.py "设备状态"  # Auto-detects and falls back if needed
```

**Action:** Use `--domain` to explicitly search other domains, or rely on `auto_fallback` (enabled by default).

### Fallback Strategy 3: Use Multi-Domain Search

```bash
# Search multiple domains when confidence is low:
python3 <skill-path>/designing-tke-frontends/scripts/search.py "设备状态" --multi-domain
```

**Action:** Use `--multi-domain` flag to search top candidate domains simultaneously.

### Fallback Strategy 4: Use Template as Fallback

If all searches fail:
1. **For Base Pages**: Use `templates/template.html` as starting point
2. **For Incremental Pages**: Use closest matching component from template
3. **Document limitations**: Inform user that exact match not found, using closest alternative

**Example:**
```
⚠️ Note: Exact match for "电梯设备状态面板" not found in TKE standards.
Using closest match: Card component with status badge.
Please verify if this meets your requirements.
```

### Fallback Strategy 5: Request More Information

If still no results after fallbacks:
- Ask user for more specific requirements
- Suggest similar components that were found
- Provide template-based solution with clear documentation

## Common Search Failure Scenarios

| Scenario | Solution |
|----------|----------|
| **No results in specified domain** | Try other domains (layout, component, pattern) |
| **Results not relevant** | Use broader keywords, try synonyms |
| **Chinese query returns nothing** | Try English keywords or use `--explain` to see why |
| **Domain auto-detection wrong** | Explicitly specify `--domain` parameter |
| **Too few results** | Increase `--max-results`, use `--multi-domain` |

## Using --explain for Debugging

When search results are unexpected, use `--explain` to understand why:

```bash
python3 <skill-path>/designing-tke-frontends/scripts/search.py "设备状态" --domain component --explain
```

This shows:
- **Match Score**: BM25 relevance score for each result
- **Matched Keywords**: Which keywords from your query matched (top 5)
- **Matched Fields**: Which CSV fields contained matches (Keywords, Usage, Use Case, etc.)
- **Synonym Expansions**: Which synonyms were automatically added to your query

**Use this to:**
- Understand why certain results were returned
- Adjust query keywords for better matches
- Debug domain detection issues
- Learn which synonyms are being used (helpful for future queries)

**Example Output:**
```
### Result 1
**Match Score:** 2.45
**Matched Keywords:** status, badge, 状态, 设备
**Matched Fields:** Keywords(status, badge), Usage(状态显示)
**Synonym Expansions:** 设备→equipment, unit
```

## Decision Flow for Search Failures

When search returns no results, follow this decision tree:

```
Search Returns 0 Results
│
├─> Step 1: Use --explain to understand why
│   └─> Check matched keywords and synonym expansions
│
├─> Step 2: Try broader keywords
│   └─> Remove specific terms, use general keywords
│
├─> Step 3: Try other domains
│   ├─> Use --domain to explicitly search layout/component/pattern
│   └─> Or rely on auto-fallback (enabled by default)
│
├─> Step 4: Use --multi-domain
│   └─> Search multiple domains simultaneously
│
├─> Step 5: Use template as fallback
│   ├─> For Base Pages: Use templates/template.html
│   └─> For Incremental: Use closest matching component
│
└─> Step 6: Request more information
    └─> Ask user for specific requirements or suggest alternatives
```

## Real-World Examples

### Example 1: Chinese Query Returns Nothing
```bash
# Original query (no results)
python3 search.py "电梯设备状态面板" --domain component

# Step 1: Use --explain to see why
python3 search.py "电梯设备状态面板" --domain component --explain
# Shows: No matches found

# Step 2: Try broader keywords
python3 search.py "设备 状态" --domain component
# Result: Badge component found

# Step 3: Try layout domain
python3 search.py "设备状态" --domain layout
# Result: Equipment Detail Page layout found
```

### Example 2: Domain Auto-Detection Wrong
```bash
# Query: "工单管理页面"
# Auto-detected: component (wrong)
# Expected: layout

# Solution: Explicitly specify domain
python3 search.py "工单管理页面" --domain layout
# Result: Work Order Management Page found
```

### Example 3: Results Not Relevant
```bash
# Query: "button"
# Returns: Many button types, but not the specific one needed

# Solution: Be more specific
python3 search.py "button primary action" --domain component
# Result: More relevant primary button found

# Or use --explain to see why certain results were returned
python3 search.py "button" --domain component --explain
# Shows: All buttons matched because "button" is too generic
```