From a8047ed0600bd803a2ebc2bb4d63392a4cb6ff4b Mon Sep 17 00:00:00 2001 From: Sergey Krylov Date: Fri, 30 Oct 2026 13:34:08 +0300 Subject: [PATCH] spec: clarify sdd-lab requirement guidance (WealthLedger/specs#66) --- .../wealth-ledger-sdd-lab/spec-writing.md | 38 +++++++++++++++---- .../wealth-ledger-sdd-lab/templates/spec.md | 6 +++ 2 files changed, 36 insertions(+), 8 deletions(-) diff --git a/openspec/schemas/wealth-ledger-sdd-lab/spec-writing.md b/openspec/schemas/wealth-ledger-sdd-lab/spec-writing.md index ccfbad5..1a6aa71 100644 --- a/openspec/schemas/wealth-ledger-sdd-lab/spec-writing.md +++ b/openspec/schemas/wealth-ledger-sdd-lab/spec-writing.md @@ -20,6 +20,12 @@ Specs определяют наблюдаемое поведение. Обосн существующего контракта. Наблюдение в коде, гипотеза и пример — не решение владельца. Неизвестное запиши в Open Decisions: вопрос, кто решает, зависимое требование и что блокируется. Несогласованные числа и варианты не становятся нормой. + Для спорного или выведенного при анализе Requirement перед первым Scenario добавь + `**Источник (ненормативно):**` — ссылку на конкретное решение Change Owner в Issue + или пункт согласованной редакции контракта. Ссылка должна оставаться пригодной из + canonical spec после archive; относительной ссылки на активный Proposal недостаточно. + Источник объясняет происхождение, но не заменяет полную норму или approval; + обоснование остаётся в Proposal. 2. **Термины.** Используй названия из затронутых canonical specs и предоставленного проектного глоссария. Один термин — одно значение в названном контексте. «Счёт», «брокерский счёт» и «учётная запись» не взаимозаменяемы. Новый или спорный термин @@ -63,8 +69,9 @@ Specs определяют наблюдаемое поведение. Обосн У ADDED/MODIFIED Requirement минимум один Scenario. GIVEN нужен, когда исходное состояние влияет на результат; WHEN задаёт событие; THEN — наблюдаемый исход с -определённым ожидаемым значением или составом, не «работает правильно». AND уточняет -тот же исход. Шаги не описывают внутренние вызовы и селекторы UI. +определённым ожидаемым значением или составом, не «работает правильно». AND продолжает +предыдущий тип шага: дополняет исходный контекст, событие или ожидаемый исход. +Шаги не описывают внутренние вызовы и селекторы UI. Сначала общее правило, затем различающие примеры: основной путь, существенная граница, иной исход, отказ, повтор или конкуренция — по применимости. Каждый сценарий @@ -168,7 +175,7 @@ Specs определяют наблюдаемое поведение. Обосн | Проход | Что проверить | | --- | --- | | Нормоконтроль | Native headings/операции; термины и единицы; явные субъект/условие/исход; атомарность; корректные ссылки; Scenario с проверяемым THEN | -| Смысл и набор | Необходимость и происхождение норм; основной путь, альтернативы, отказы и границы; повторы/конкуренция/сохранность по риску; непротиворечивость таблиц и итогового baseline; отсутствие выдуманных решений | +| Смысл и набор | Необходимость и происхождение норм (у спорных/выведенных — источник действительно подтверждает норму, ссылка пригодна после archive); основной путь, альтернативы, отказы и границы; повторы/конкуренция/сохранность по риску; непротиворечивость таблиц и итогового baseline; отсутствие выдуманных решений | Проверь не только delta, но и получающийся набор вместе с canonical specs: сохранились ли действующие ограничения, исключения, инварианты и сценарии? MODIFIED @@ -193,11 +200,26 @@ Gate Log, без нового отчёта на каждый Requirement. ### Trial -Для проверки эффекта дай одним и тем же авторам/моделям одинаковые входы: простое -правило, ветвление, повтор/состояние и MODIFIED. До сравнения зафиксируй согласованные -исходы и намеренно оставленные неизвестные. Сравни ответы независимых читателей на -контрольные вопросы, пропуски и выдуманные нормы, время уточнения и ревью. Совпадение -формулировок и успешный CLI не считаются доказательством одинакового понимания. +Эффект профиля проверяется сравнительным пилотом; до результатов он не подтверждён. + +1. До запуска зафиксируй четыре одинаковых для обеих версий задания: простое правило, + ветвление, повтор/состояние и MODIFIED с исходной canonical spec. Для оценки отдельно + запиши согласованные исходы, намеренно оставленные неизвестные и контрольные вопросы. +2. Сравни прежнюю и изменённую инструкции минимум на двух авторах/моделях, каждый + выполняет обе версии. Сохрани входы, prompts, версии инструкций и моделей, доступные + настройки и результаты. Для LLM используй отдельные сессии без ответов другой версии; + для людей чередуй порядок версий, чтобы уменьшить эффект обучения. +3. Независимые читатели отвечают на одинаковые контрольные вопросы по полученным + спецификациям, не зная автора и версии инструкции. Ответы для оценки из шага 1 + раскрываются после чтения; согласие читателей само по себе не означает правильность. +4. По каждому заданию сравни расхождения трактовок, ошибки относительно согласованных + исходов, пропущенные случаи, выдуманные нормы и время уточнения/ревью. Сохрани + конкретные примеры ошибок вместе с результатами в Issue пилота. +5. Критерий улучшения согласуй до запуска: меньше смысловых расхождений без роста + ошибок, пропусков и выдуманных норм; допустимое изменение времени определяет владелец. + Если различий нет или данных недостаточно, эффект не подтверждён. Вывод ограничен + проверенными заданиями и авторами/моделями. Совпадение формулировок и успешный CLI + не считаются доказательством одинакового понимания. ## Sources and Adaptation diff --git a/openspec/schemas/wealth-ledger-sdd-lab/templates/spec.md b/openspec/schemas/wealth-ledger-sdd-lab/templates/spec.md index c850685..e675091 100644 --- a/openspec/schemas/wealth-ledger-sdd-lab/templates/spec.md +++ b/openspec/schemas/wealth-ledger-sdd-lab/templates/spec.md @@ -21,9 +21,15 @@ SHALL NOT — запрет; существующие MUST/MUST NOT равноз Сценарий: GIVEN — существенное исходное состояние, WHEN — событие, THEN — конкретный наблюдаемый исход. Минимум один Scenario; границы/отказы/повторы добавляй по смыслу. Новое правило в одном лишь сценарии недопустимо. +AND дополняет предыдущий тип шага GIVEN/WHEN/THEN. Термины определены, величины имеют единицы и границы. Неизвестное — вопрос в Open Decisions с владельцем и зависимым требованием, не придуманный ответ. +Для спорного/выведенного Requirement укажи источник перед первым Scenario по профилю. +Пример формата (подставь реальное согласованное решение): +**Источник (ненормативно):** [решение владельца](), пункт «Границы периода». +Ссылка остаётся пригодной после archive; норму полностью сформулируй в Requirement. + Учебный образец формы, не продуктовая политика: ## ADDED Requirements ### Requirement: Отбор операций за календарный период