Доказательства и оценка R_eff

Почему это важно

Большинство команд принимают решения, основываясь на интуиции, опыте или авторитете («так сказал старший инженер»). Это работает до тех пор, пока не перестаёт. Когда происходит инцидент на производстве и кто-то спрашивает: «Почему мы думали, что это сработает?», ответ обычно звучит так: «Мы просто… думали, что сработает».

Принятие решений, основанных на доказательствах, заменяет «поверьте мне» на «вот данные». Речь идёт не о бюрократии, а о том, чтобы знать, какие из ваших решений надёжны, а какие основаны на непроверенных предположениях. Показатель R_eff в Forgeplan даёт вам одно число, которое отвечает на вопрос: насколько я должен доверять этому решению?

Самое ценное не высокий балл, а обнаружение низкого. Решение с R_eff = 0.1 точно указывает на то, где находится ваш риск, прежде чем он превратится в производственный инцидент.

Принцип

Доверие - это не чувство. Это измерение.

Каждое решение в Forgeplan имеет показатель R_eff - число, которое говорит вам, насколько оно надёжно, основываясь на фактических доказательствах.

Формула R_eff

R_eff = min(evidence_scores)

Не среднее, а минимум. Ваше решение настолько сильно, насколько сильно ваше слабое доказательство. Три сильных доказательства + одно непроверенное предположение = непроверенное решение.

Этот выбор дизайна преднамерен. Усреднение позволило бы сильным доказательствам маскировать слабые места. Представьте мост: если три опоры прочны, но одна треснула, вы не усредняете прочность опор. Вы чините треснувшую.

Расчёт оценки доказательства

evidence_score = max(0, verdict_score - CL_penalty)

Оценки вердиктов

Вердикт	Оценка	Значение
supports	1.0	Доказательство подтверждает решение
weakens	0.5	Доказательство вызывает опасения
refutes	0.0	Доказательство противоречит решению

Штрафы за уровень конгруэнтности

Насколько доказательство близко к вашему реальному контексту? Доказательство из вашего собственного проекта стоит больше, чем доказательство из поста в блоге.

Уровень	Штраф	Пример
CL3	0.0	Запуск бенчмарка в этом проекте, модульный тест в этой кодовой базе
CL2	0.1	PoC в связанном модуле, тест в соседнем проекте
CL1	0.4	Внешняя документация, чужой пост в блоге, выступление на конференции
CL0	0.9	Ответ со Stack Overflow из другого языка/контекста, противоположная область

Почему это важно: Пост в блоге, утверждающий «Redis быстрый» (CL1, штраф 0.4), стоит гораздо меньше, чем ваш собственный бенчмарк, показывающий, что Redis справляется с вашей рабочей нагрузкой (CL3, штраф 0.0). Система штрафов заставляет вас ценить прямые доказательства выше слухов.

Рабочий пример

Вы решаете, использовать ли LanceDB для хранения артефактов. Вы собираете три доказательства:

1. Ваш бенчмарк на 10K записей: supports (1.0) на CL2 (протестировано в PoC, не в продакшене) -> оценка = 1.0 - 0.1 = 0.9
2. Документация LanceDB Rust SDK: supports (1.0) на CL1 (внешняя документация) -> оценка = 1.0 - 0.4 = 0.6
3. Комментарий на Hacker News о продакшн-использовании: weakens (0.5) на CL1 (внешний, непроверенный) -> оценка = 0.5 - 0.4 = 0.1

R_eff = min(0.9, 0.6, 0.1) = 0.1 -- В ЗОНЕ РИСКА

Слабым звеном является непроверенная проблема с продакшеном. Чтобы улучшить R_eff, вам нужны либо более сильные доказательства готовности к продакшену (проведите собственное продакшн-тестирование, CL3), либо удалить это опасение из вашего набора доказательств, если оно не относится к вашему варианту использования.

Устаревание доказательств

Доказательства имеют TTL (поле valid_until). Когда срок действия истекает:

• Доказательство не удаляется - оно становится просроченным
• Оценка падает до 0.1 (просроченное не то же самое, что отсутствующее)
• forgeplan stale обнаруживает просроченные доказательства
• forgeplan renew продлевает срок действия с помощью новых доказательств

Устаревание существует, потому что мир меняется. Ваш бенчмарк полугодовой давности был запущен на другой версии библиотеки, другом оборудовании, другом объёме данных. Просроченное доказательство не бесполезно - оно говорит вам, что что-то было правдой когда-то. Но оно не должно давать вам полной уверенности в настоящем.

Создание доказательств

# Создать EvidencePack
forgeplan new evidence "Auth benchmark -- JWT 2ms, 12 tests pass"

# Привязать к решению, которое оно поддерживает
forgeplan link EVID-001 PRD-001 --relation informs

# Проверить влияние
forgeplan score PRD-001
# -> R_eff = 1.00

Обязательные структурированные поля

Каждый EvidencePack ДОЛЖЕН содержать в своём теле:

## Structured Fields

verdict: supports
congruence_level: 3
evidence_type: measurement

Поле	Значения	Описание
verdict	supports / weakens / refutes	Это доказательство подтверждает или противоречит решению?
congruence_level	0-3	Насколько контекст доказательства близок к вашему реальному контексту?
evidence_type	measurement / test / benchmark / audit	Какой это тип доказательства?

Без этих полей парсер R_eff не может извлечь данные для оценки и по умолчанию использует CL0 (штраф 0.9). Это самая распространённая причина неожиданно низких оценок R_eff.

Что делает доказательство хорошим

• Тесты, которые проходят в CI - CL3, evidence_type: test. Самая надёжная форма, потому что они запускаются в вашей реальной кодовой базе.
• Бенчмарки на ваших данных - CL3, evidence_type: benchmark. Измеряет производительность в вашем реальном контексте.
• PoC в связанном модуле - CL2, evidence_type: measurement. Хорошо, но не так сильно, как продакшн-доказательство.
• Внешняя документация - CL1, evidence_type: measurement. Полезна, но несёт штраф 0.4. Дополняйте собственным тестированием.

Пороги доверия

R_eff	Статус	Действие
>= 0.5	Адекватно	Решение может быть принято
< 0.5	Требует проверки	Добавьте доказательства или пересмотрите
< 0.3	В ЗОНЕ РИСКА	Решение ненадёжно, переоцените
0.0	Слепое пятно	Доказательств нет вообще

Слепое пятно (R_eff = 0.0) - самое опасное состояние. Это означает, что вы приняли решение без каких-либо подтверждающих доказательств. forgeplan health заметно помечает их, потому что они представляют собой неизвестный риск.

Команды

forgeplan score PRD-001     # Показать R_eff + детализацию доказательств
forgeplan decay             # Показать влияние устаревания доказательств
forgeplan blindspots        # Найти решения без доказательств
forgeplan health            # Полная панель состояния проекта

Подводные камни

• Забыли структурированные поля в теле доказательства. Это ошибка номер один. Без verdict, congruence_level и evidence_type парсер присваивает CL0, и ваш R_eff падает почти до нуля.
• Преувеличение CL3. Бенчмарк, который вы однажды запустили на своём ноутбуке, не является CL3. CL3 означает, что доказательство было собрано в том же контексте, где будет применяться решение - та же кодовая база, та же среда, тот же масштаб.
• Игнорирование доказательств, которые “ослабляют”. Если вы нашли доказательства того, что выбранный подход имеет проблемы, запишите их с verdict: weakens. Сокрытие неудобных доказательств не заставит их исчезнуть; это просто сделает ваш R_eff нечестным.
• Никогда не обновляете доказательства. Бенчмарки и результаты тестов имеют срок годности. Установите valid_until на 90-180 дней и устраняйте просроченные доказательства, когда forgeplan health их помечает.
• Привязка доказательств к неправильному артефакту. Доказательства должны быть привязаны к решению, которое они поддерживают, а не к Epic или к несвязанному PRD. Неправильно привязанный EvidencePack не даёт преимуществ R_eff.

Подводные камни и примечания по миграции

PROB-034 (v0.17.2) - ловушка многострочного HTML-комментария

Шаблон доказательства по умолчанию поставляется с многострочным HTML-комментарием справки:

<!--
     verdict: supports | weakens | refutes
     congruence_level: 0 | 1 | 2 | 3 (CL3=same context, CL0=opposed)
-->

До версии v0.17.2 extract_field не отслеживал состояние многострочного комментария. Строка-заполнитель congruence_level: 0 | 1 | 2 | 3 (CL3=...) сопоставлялась так, как если бы это было реальное структурированное поле, нечисловое значение не удавалось разобрать, explicit_cl становилось None, и парсер молча устанавливал значение по умолчанию CL3 (без штрафа). Это означало, что каждый артефакт доказательства, созданный с помощью шаблона по умолчанию начиная с v0.17.0, имел затенённый реальный congruence_level - R_eff был искусственно завышен во всём рабочем пространстве.

v0.17.2 реализует правильный конечный автомат состояния многострочного комментария, который пропускает все строки между <!-- и -->.

Если у вас есть доказательства, созданные до v0.17.2, повторно запустите оценку после обновления:

forgeplan score --all

Старые значения R_eff могут упасть - это правильно. Предыдущие значения были молчаливо неверными. Любое доказательство, которое явно устанавливало congruence_level в разделе Structured Fields, теперь будет учитываться, и низкие значения CL будут правильно штрафовать R_eff.

Приоритет SourceTier - консервативное правило min()

Когда артефакт имеет как тег source_tier, так и явный congruence_level в своих структурированных полях, система принимает min(tier_cl, explicit_cl) - побеждает более консервативное значение. Тег никогда не может повысить доверие сверх того, что заявлено в структурированных полях.

Это защищает от атак по повышению CL путём манипуляции тегами: пометка артефакта source_tier=T1 не отменяет явный congruence_level: 0 в теле. См. forgeplan tag - Source Tier и сопоставление CL для полной таблицы соответствия уровней CL и примеров.

Связанные материалы

• CLI: forgeplan score, forgeplan blindspots, forgeplan decay, forgeplan health
• CLI: forgeplan new, forgeplan link
• Жизненный цикл артефакта - просроченные доказательства и продление
• Рассуждения ADI - фаза индукции потребляет доказательства
• Руководство по первому артефакту - создание доказательств на практике