spec: clarify sdd-lab requirement guidance (WealthLedger/specs#66)
Conventional commits / commits (pull_request) Successful in 12s
Specs security / security (pull_request) Successful in 9s
Specs verify / verify (pull_request) Successful in 10s

This commit is contained in:
2026-10-30 13:34:19 +03:00
parent 4c13b1863f
commit a8047ed060
2 changed files with 36 additions and 8 deletions
@@ -20,6 +20,12 @@ Specs определяют наблюдаемое поведение. Обосн
существующего контракта. Наблюдение в коде, гипотеза и пример — не решение существующего контракта. Наблюдение в коде, гипотеза и пример — не решение
владельца. Неизвестное запиши в Open Decisions: вопрос, кто решает, зависимое владельца. Неизвестное запиши в Open Decisions: вопрос, кто решает, зависимое
требование и что блокируется. Несогласованные числа и варианты не становятся нормой. требование и что блокируется. Несогласованные числа и варианты не становятся нормой.
Для спорного или выведенного при анализе Requirement перед первым Scenario добавь
`**Источник (ненормативно):**` — ссылку на конкретное решение Change Owner в Issue
или пункт согласованной редакции контракта. Ссылка должна оставаться пригодной из
canonical spec после archive; относительной ссылки на активный Proposal недостаточно.
Источник объясняет происхождение, но не заменяет полную норму или approval;
обоснование остаётся в Proposal.
2. **Термины.** Используй названия из затронутых canonical specs и предоставленного 2. **Термины.** Используй названия из затронутых canonical specs и предоставленного
проектного глоссария. Один термин — одно значение в названном контексте. «Счёт», проектного глоссария. Один термин — одно значение в названном контексте. «Счёт»,
«брокерский счёт» и «учётная запись» не взаимозаменяемы. Новый или спорный термин «брокерский счёт» и «учётная запись» не взаимозаменяемы. Новый или спорный термин
@@ -63,8 +69,9 @@ Specs определяют наблюдаемое поведение. Обосн
У ADDED/MODIFIED Requirement минимум один Scenario. GIVEN нужен, когда исходное У ADDED/MODIFIED Requirement минимум один Scenario. GIVEN нужен, когда исходное
состояние влияет на результат; WHEN задаёт событие; THEN — наблюдаемый исход с состояние влияет на результат; WHEN задаёт событие; THEN — наблюдаемый исход с
определённым ожидаемым значением или составом, не «работает правильно». AND уточняет определённым ожидаемым значением или составом, не «работает правильно». AND продолжает
тот же исход. Шаги не описывают внутренние вызовы и селекторы UI. предыдущий тип шага: дополняет исходный контекст, событие или ожидаемый исход.
Шаги не описывают внутренние вызовы и селекторы UI.
Сначала общее правило, затем различающие примеры: основной путь, существенная Сначала общее правило, затем различающие примеры: основной путь, существенная
граница, иной исход, отказ, повтор или конкуренция — по применимости. Каждый сценарий граница, иной исход, отказ, повтор или конкуренция — по применимости. Каждый сценарий
@@ -168,7 +175,7 @@ Specs определяют наблюдаемое поведение. Обосн
| Проход | Что проверить | | Проход | Что проверить |
| --- | --- | | --- | --- |
| Нормоконтроль | Native headings/операции; термины и единицы; явные субъект/условие/исход; атомарность; корректные ссылки; Scenario с проверяемым THEN | | Нормоконтроль | Native headings/операции; термины и единицы; явные субъект/условие/исход; атомарность; корректные ссылки; Scenario с проверяемым THEN |
| Смысл и набор | Необходимость и происхождение норм; основной путь, альтернативы, отказы и границы; повторы/конкуренция/сохранность по риску; непротиворечивость таблиц и итогового baseline; отсутствие выдуманных решений | | Смысл и набор | Необходимость и происхождение норм (у спорных/выведенных — источник действительно подтверждает норму, ссылка пригодна после archive); основной путь, альтернативы, отказы и границы; повторы/конкуренция/сохранность по риску; непротиворечивость таблиц и итогового baseline; отсутствие выдуманных решений |
Проверь не только delta, но и получающийся набор вместе с canonical specs: Проверь не только delta, но и получающийся набор вместе с canonical specs:
сохранились ли действующие ограничения, исключения, инварианты и сценарии? MODIFIED сохранились ли действующие ограничения, исключения, инварианты и сценарии? MODIFIED
@@ -193,11 +200,26 @@ Gate Log, без нового отчёта на каждый Requirement.
### Trial ### Trial
Для проверки эффекта дай одним и тем же авторам/моделям одинаковые входы: простое Эффект профиля проверяется сравнительным пилотом; до результатов он не подтверждён.
правило, ветвление, повтор/состояние и MODIFIED. До сравнения зафиксируй согласованные
исходы и намеренно оставленные неизвестные. Сравни ответы независимых читателей на 1. До запуска зафиксируй четыре одинаковых для обеих версий задания: простое правило,
контрольные вопросы, пропуски и выдуманные нормы, время уточнения и ревью. Совпадение ветвление, повтор/состояние и MODIFIED с исходной canonical spec. Для оценки отдельно
формулировок и успешный CLI не считаются доказательством одинакового понимания. запиши согласованные исходы, намеренно оставленные неизвестные и контрольные вопросы.
2. Сравни прежнюю и изменённую инструкции минимум на двух авторах/моделях, каждый
выполняет обе версии. Сохрани входы, prompts, версии инструкций и моделей, доступные
настройки и результаты. Для LLM используй отдельные сессии без ответов другой версии;
для людей чередуй порядок версий, чтобы уменьшить эффект обучения.
3. Независимые читатели отвечают на одинаковые контрольные вопросы по полученным
спецификациям, не зная автора и версии инструкции. Ответы для оценки из шага 1
раскрываются после чтения; согласие читателей само по себе не означает правильность.
4. По каждому заданию сравни расхождения трактовок, ошибки относительно согласованных
исходов, пропущенные случаи, выдуманные нормы и время уточнения/ревью. Сохрани
конкретные примеры ошибок вместе с результатами в Issue пилота.
5. Критерий улучшения согласуй до запуска: меньше смысловых расхождений без роста
ошибок, пропусков и выдуманных норм; допустимое изменение времени определяет владелец.
Если различий нет или данных недостаточно, эффект не подтверждён. Вывод ограничен
проверенными заданиями и авторами/моделями. Совпадение формулировок и успешный CLI
не считаются доказательством одинакового понимания.
## Sources and Adaptation ## Sources and Adaptation
@@ -21,9 +21,15 @@ SHALL NOT — запрет; существующие MUST/MUST NOT равноз
Сценарий: GIVEN — существенное исходное состояние, WHEN — событие, Сценарий: GIVEN — существенное исходное состояние, WHEN — событие,
THEN — конкретный наблюдаемый исход. Минимум один Scenario; границы/отказы/повторы THEN — конкретный наблюдаемый исход. Минимум один Scenario; границы/отказы/повторы
добавляй по смыслу. Новое правило в одном лишь сценарии недопустимо. добавляй по смыслу. Новое правило в одном лишь сценарии недопустимо.
AND дополняет предыдущий тип шага GIVEN/WHEN/THEN.
Термины определены, величины имеют единицы и границы. Неизвестное — вопрос в Термины определены, величины имеют единицы и границы. Неизвестное — вопрос в
Open Decisions с владельцем и зависимым требованием, не придуманный ответ. Open Decisions с владельцем и зависимым требованием, не придуманный ответ.
Для спорного/выведенного Requirement укажи источник перед первым Scenario по профилю.
Пример формата (подставь реальное согласованное решение):
**Источник (ненормативно):** [решение владельца](<URL-комментария-Issue>), пункт «Границы периода».
Ссылка остаётся пригодной после archive; норму полностью сформулируй в Requirement.
Учебный образец формы, не продуктовая политика: Учебный образец формы, не продуктовая политика:
## ADDED Requirements ## ADDED Requirements
### Requirement: Отбор операций за календарный период ### Requirement: Отбор операций за календарный период