Руководство по проверкам качества решений в Forgeplan. Объединяет Verification Gate (Quint-code), Adversarial Review (BMAD), 13-Step PRD Validation (BMAD) и R_eff Quality Scoring (Quint-code/FPF).
Перед закрытием любого решения (DecisionRecord, ADR, RFC) проверь все 5 пунктов. Это защита от самообмана и confirmation bias.
Что должно быть истинным, если решение верно?
Если решение X правильное, то обязательно должны выполняться условия Y, Z, W. Проверь каждое. Если хотя бы одно не выполняется — решение под вопросом.
Пример: Если мы решили использовать LanceDB, то должно быть верно:
- LanceDB поддерживает наши типы данных (structured + vectors)
- Производительность на 10K артефактов приемлема (<100ms запрос)
- Есть стабильный Rust SDK
Настоящий (не strawman) контраргумент против решения.
Сформулируй самый сильный аргумент ПРОТИВ выбранного варианта. Strawman (заведомо слабый аргумент) не считается — нужен реальный risk.
Пример: "LanceDB — молодой проект, API может сломаться между версиями. SQLite стабилен 20+ лет."
Доказательства только из этой сессии? -> CL1 penalty.
Если все evidence получены в рамках одной сессии (один разговор, один PoC), это CL1 — ограниченная конгруэнтность. Нужны внешние подтверждения: документация, бенчмарки других проектов, production опыт.
Штраф: CL1 = 0.4 penalty к R_eff score.
Сценарии с вероятностью <10% каждый, но катастрофическими последствиями.
Перечисли 2-3 сценария "что если всё пойдёт не так". Оцени: можем ли мы их пережить? Есть ли rollback plan?
Пример:
- LanceDB прекращает разработку (вероятность ~5%) -> данные в открытом формате Lance, можно мигрировать
- Embedding модель BGE-M3 удалена из HuggingFace (~2%) -> модель встроена в бинарник, работает оффлайн
Действительно ли это самое слабое звено, или есть скрытое?
R_eff = min(evidence_scores). Убедись, что ты определил НАСТОЯЩЕЕ слабое звено. Часто реальный risk скрыт за тем, что кажется очевидным.
Вопрос: "Я считаю, что слабое звено — производительность. Но может быть, реальная проблема — developer experience или миграция существующих данных?"
Протокол ревью из BMAD-METHOD. Применяется на уровнях Deep и Critical.
-
Ревьюер ОБЯЗАН найти проблемы. Это не опционально — если ревьюер не нашёл ни одной проблемы, значит ревью проведено поверхностно.
-
0 найденных проблем = повторить ревью. Ноль проблем указывает на approval bias. Ревьюер должен провести ревью заново с повышенным вниманием.
-
Классификация серьёзности:
| Severity | Описание | Действие |
|---|---|---|
| Critical | Блокирует реализацию, фундаментальный дефект | Обязательно исправить до продолжения |
| Warning | Потенциальная проблема, неполнота, неясность | Исправить или обосновать почему оставляем |
| Pass | Замечание, улучшение, стилистика | На усмотрение автора |
- Каждый finding должен ссылаться на конкретную секцию или строку. Абстрактные замечания ("надо бы улучшить") не принимаются.
1. Автор готовит артефакт (PRD, RFC, ADR, Spec)
2. Ревьюер получает артефакт
3. Ревьюер ИЩЕТ проблемы (не подтверждения)
4. Ревьюер составляет список findings с severity
5. Если findings = 0 -> повторное ревью
6. Автор обрабатывает каждый finding:
- Critical -> исправляет
- Warning -> исправляет или документирует обоснование
- Pass -> на своё усмотрение
7. Повторное ревью исправлений (для Critical)На уровне Critical проводится минимум 2 раунда Adversarial Review. Второй раунд фокусируется на:
- Проверке исправлений из первого раунда
- Поиске проблем, возникших из-за исправлений
- Межсекционной согласованности
Полная валидация PRD по 13 шагам из BMAD-METHOD. Применяется на уровнях Deep и Critical.
| Шаг | Название | Что проверяет |
|---|---|---|
| 1 | Discovery & Confirmation | Тип документа определён корректно, задача ясна |
| 2 | Format Detection & Structure | Структура соответствует шаблону, все секции на месте |
| 3 | Information Density | Нет filler/fluff, каждое предложение несёт смысл |
| 4 | Product Brief Coverage | Product brief полностью покрыт: проблема, аудитория, цели |
| 5 | Measurability | FR и NFR тестируемы и измеримы (числа, метрики) |
| 6 | Traceability | Цепочка: Summary -> Criteria -> User Journeys -> FRs прослеживается |
| 7 | Implementation Leakage | Нет имён фреймворков, библиотек, технологий в требованиях |
| 8 | Domain Compliance | Учтены доменные требования (healthcare, fintech, и т.д.) |
| 9 | Project-Type Compliance | Учтена специфика типа проекта (API, mobile, web, CLI) |
| 10 | SMART Requirements | Specific, Measurable, Attainable, Relevant, Traceable |
| 11 | Holistic Quality Assessment | Общая оценка 1-5 по качеству документа |
| 12 | Completeness | Нет template variables ({{placeholder}}), все секции заполнены |
| 13 | Report Finalization | Итоговый отчёт с рекомендациями и action items |
На уровне Standard обязательны только 3 шага:
- Шаг 3 (Information Density) — убрать воду
- Шаг 5 (Measurability) — FR/NFR должны быть тестируемы
- Шаг 7 (Implementation Leakage) — требования без привязки к реализации
Система оценки качества решений из Quint-code. Основной принцип: доверие к решению = его слабейшее звено.
R_eff = min(evidence_scores)НИКОГДА среднее (average). Одно слабое доказательство обрушивает весь score.
Какая эвиденция участвует: min идёт только по текущей эвиденции артефакта. Пакеты с терминальным статусом (superseded/deprecated) исключаются — вытесненный пакет остаётся в графе как история, но больше не говорит о текущей надёжности (ADR-020, зеркало dependency-пропуска ADR-002). Draft-эвиденция считается (это штатное состояние свежего измерения до активации). Активный refutes по-прежнему обнуляет score; путь восстановления — честное вытеснение: слинковать пакет ре-верификации и supersede <старый> --by <новый>.
evidence_score = max(0, verdict_score - CL_penalty)| Verdict | Score | Описание |
|---|---|---|
supports |
1.0 | Evidence подтверждает решение |
weakens |
0.5 | Evidence ослабляет уверенность |
refutes |
0.0 | Evidence опровергает решение |
| Congruence Level | Penalty | Описание |
|---|---|---|
| CL3 | 0.0 | Тот же контекст, внутренний тест |
| CL2 | 0.1 | Похожий контекст, related project |
| CL1 | 0.4 | Другой контекст, внешняя документация |
| CL0 | 0.9 | Противоположный контекст |
Каждый evidence имеет поле valid_until (TTL). После истечения:
- Evidence НЕ удаляется
- Score становится 0.1 (stale, not absent)
- Это отличие от 0.0 — stale evidence лучше, чем полное отсутствие
| R_eff | Статус | Действие |
|---|---|---|
| >= 0.5 | Adequate | Решение можно принять |
| < 0.5 | Needs Review | Требуется дополнительный evidence или пересмотр |
| < 0.3 | AT RISK | Решение ненадёжно, необходима переоценка |
Решение: "Использовать LanceDB для хранения артефактов"
Evidence pack:
- Бенчмарк на 10K записей: supports (1.0), CL2 -> score = 1.0 - 0.1 = 0.9
- Документация LanceDB по Rust SDK: supports (1.0), CL1 -> score = 1.0 - 0.4 = 0.6
- Отзывы в production: weakens (0.5), CL1 -> score = 0.5 - 0.4 = 0.1
R_eff = min(0.9, 0.6, 0.1) = 0.1 — AT RISKСлабое звено — отзывы о production использовании. Нужен дополнительный evidence (CL2+) или пересмотр.
| Уровень глубины | Verification Gate | Adversarial Review | 13-Step Validation | R_eff Scoring |
|---|---|---|---|---|
| Tactical | Нет | Нет | Нет | Нет |
| Standard | Да (3 из 5 пунктов) | Нет | Частично (шаги 3, 5, 7) | Опционально |
| Deep | Да (все 5 пунктов) | Да | Полные 13 шагов | Да |
| Critical | Да (все 5 пунктов) | Да, несколько раундов | Полные 13 шагов + domain | Да, обязательно |
На уровне Standard обязательны минимум 3 из 5 пунктов. Рекомендуемые:
- Deductive consequences — всегда полезно
- Strongest counter-argument — защита от confirmation bias
- WLNK challenge — определить реальное слабое звено
Пункты 3 (Self-evidence check) и 4 (Tail failure scenarios) опциональны на Standard, но рекомендуются при любых сомнениях.
- DEPTH-CALIBRATION.md — когда какой уровень глубины
- PRD-RFC-ADR-FLOW.md — decision tree: какой документ создать
- ARTIFACT-MODEL.md — иерархия артефактов и lifecycle