xgaida-x-nixi-gdd-scribe

# GDD Scribe — рабочий контур геймдизайн-документации Этот скилл — процедура, а не справка. Он держит ГДД как **единый источник правды**: решения не теряются и не расходятся по документам, термины единообразны, а порядок и статус машиночитаемы. Цель — чтобы дизайн-мысль Макса попадала в доки один раз, в правильное место, и не рассыпалась при следующем переписывании. ## Роль: писарь-редактор (не соавтор-самозванец) - Я **оформляю и разношу РЕШЕНИЯ Макса**, слежу за консистентностью, ловлю противоречия. - Я могу **предлагать дизайн и спорить** — экспертное несогласие важнее поддакивания. - Но в журнал принятых решений идёт **только то, что Макс принял**. Своё предложение помечаю статусом `proposed`, НИКОГДА не выдаю за `accepted`. Финальное решение — Макса. ## Карта ГДД Vault: `docs/wiki/` (Obsidian, публикуется Quartz на GitHub Pages). ГДД — `docs/wiki/gdd/`. | Что | Где (текущее) | |---|---| | Индекс ГДД (MOC, легенда статусов) | `docs/wiki/gdd/00-meta/index.md` | | **Журнал принятых решений (ADR)** | `docs/wiki/gdd/00-meta/journal-adr.md` | | Roadmap ГД (только НЕрешённое) | `docs/wiki/gdd/00-meta/roadmap.md` | | **Инбокс Макса** (его черновик, я туда не пишу) | `docs/wiki/gdd/00-meta/open.md` + архив `inbox/` | | Развилки без вердикта, неутверждённое, инкубатор | `docs/wiki/gdd/00-meta/open-forks.md` | | Глоссарий терминов (RU\|EN) | `docs/wiki/gdd/00-meta/glossary.md` | | Нормативный справочник тегов | `docs/wiki/gdd/roster/tag-reference.md` | | Легаси (снятые механики) | `docs/wiki/gdd/00-meta/legacy.md` | | Главы дизайна (кластеры) | `docs/wiki/gdd/{10-vision,20-combat,30-run-meta,40-content,50-modes-ux}/<slug>.md` | | Карточки контента | `docs/wiki/gdd/{relics,roster,enemies,enemies/factions}/` | | Research-разборы жанра | `docs/wiki/research/` — **выведен из-под правила 4** (решено 2026-07-26): архив ресёрча, а не канон; шапки и статусы готовности с него не требуются, линт его не проверяет | | Тех-вика (НЕ ГДД) | `docs/wiki/tech/` — инженерные доки, чужая территория | | **Кластеры ГДД в чужих контурах** | `60-narrative/` — скилл `narrative`; `70-gamefeel/` — скилл `gamefeel-vfx` (решено 2026-07-31). Писарь их не правит | > **Почему два кластера отданы:** писарь владеет чистым геймдизайном — механиками, балансом, > контентом. В нарративе и джусе дизайн неотделим от реализации (тайминг эффекта — одновременно > решение дизайнера и число в конфиге), и деление по двум скиллам развело бы один факт по двум > головам. Журнал решений `00-meta/journal-adr.md` при этом остаётся общим — туда пишут все. > **Статус:** миграция выполнена. ВСЕ доки (главы, служебные, roster, И карточки > `relics/enemies/factions`) — латинские слаги + `title` по системе `Cluster - Name` > (см. правило 4); README каждой папки = `index.md`. Карточки переведены на слаги > 2026-07-16 (`the-bloom.md`, `bandit-bruiser.md`, `goblins.md`); `.base` показывает > `title`, не `file.name`. Сверяйся с `00-meta/index.md` (MOC). ## Пять правил, нарушение которых = переделка (HARD) 1. **Журнал решений — append-only ADR.** Принятое решение пишется в `0.7` с датой (в заголовке сессии) и **причиной** (обязательная колонка). Принятое НИКОГДА не затирается: если решение меняется — старая запись помечается `superseded` со ссылкой на новую, а не переписывается. *Почему:* видна эволюция «почему менялось» (лекарство от «переписал модель огня три раза»); затёртая история = потеря контекста и повтор старых ошибок. См. `references/decision-journal-adr.md`. 2. **Решено → разнесено (single source).** Каждый факт живёт в ОДНОМ канон-доме (главе). Приняв решение, я в тот же заход разношу его во ВСЕ затронутые канон-документы и указываю в журнале, куда разнесено. Дубль факта в двух местах = запрещён. *Почему:* главный паттерн нашего аудита — «decided-but-not-distributed»: решили, записали, но не протащили в главы, и они разошлись. Разнос в тот же заход убивает это. 3. **Термины — через глоссарий.** Любой игровой термин сверяется с `0.4. Локализация` (+ `Справочник тегов`). EN-канон для сущностей (реликвии/Арканы/id — по-английски, `The Pyre`). Новый термин сначала в глоссарий, потом в текст. Расхождение — чинить или флагать, не плодить синоним. *Почему:* рассинхрон терминов (Перк vs Trait, «Обычная» на двух осях) — тихий источник багов реализации и путаницы. См. `references/terminology-and-canon.md`. 4. **Мета — в frontmatter, не в тексте и не в имени.** Каждый ГДД-док несёт YAML-шапку: `title` (система `Cluster - Name`, см. ниже), `order` (число — порядок), `status` (`draft|needs_review|ready|living|archive`), `pillars` (опц.), `updated`. Порядок главы задаётся `order`, НЕ номером в имени файла; статус — полем, не текстовой строкой. *Почему:* порядок, отвязанный от имени, переставляется без переименования → ссылки не ломаются; машиночитаемый статус собирается в Dataview-дашборд «что готово». См. `references/structure-and-frontmatter.md`. **Система тайтлов (решено 2026-07-16, EN):** `title = "<Кластер> - <Имя>"`, разделитель ` - `, весь `title` на английском (по всему vault). Кластер — ярлык папки: `Meta`, `Vision`, `Combat`, `Run`, `Content`, `Modes`, `Roster`. Карточки-сущности: `Relic - <Common|Unique> - <Name (Class)>`, враги `<Faction> - <Tier> - <Name>`, фракции `Faction - <Name>`. Обзорный файл раздела не дублирует префикс (`combat-system` → `Combat - System`). Имя файла — короткий слаг; `title` показывают Front Matter Title (встроенный проводник) и пропатченный File Tree Alternative (`docs/obsidian/filetree-frontmatter-patch.py` — title + сортировка по `order`). 5. **Карточка контента держит ТОЛЬКО механику.** Принято Максом 2026-07-28, применено ко всем 30 карточкам 2026-07-30 (журнал `2026-07-30/1`). Карточка реликвии, врага, босса, предмета отвечает на один вопрос — «что и как работает сейчас»: числа, кулдауны, что делает навык, AI-настройки. Всё прочее уезжает по маршруту: | Факт | Дом | |---|---| | почему выбрали так, что отвергли, «решение Макса от…» | `00-meta/journal-adr.md` | | «*Реализовано <дата>*», «Чего требует от движка», расхождение с кодом | `relics/implementation-status.md`, `enemies/implementation-status.md` | | неутверждённые числа и имена, `proposed`, «класс не задан», незаполненные поля | `00-meta/open-forks.md` §2.5 | | «Баланс-флаги», что и как замерить | `docs/balance-issues.md` | | идея без вердикта, отложенный вариант | `relics/draft-ideas.md` | Число пишется **как число**: «щит 120 на 4 сек», а не «щит *(`proposed`: 120)*» — оговорка живёт в `open`, число в карточке. Строки `**Статус:** Черновик` в теле нет: статус держит поле `status`. Поле `needs_review` — **только** открытые вопросы по тегам, никогда не заявки на реализацию. Внизу карточки — блок ссылок на дома (образец в `relics/template-relic-card.md` §HARD). *Почему:* у карточки одна работа — ответить «что работает сейчас». Провенанс внутри неё делает раздел нечитаемым (прямая жалоба Макса 2026-07-30: «мне очень сложно читать») и заводит второго владельца факта: при следующей правке механики карточка и её же врезки расходятся. ## Артефакты сильного ГДД (к чему ведём) Апгрейд утверждён «по-крупному» — скилл поддерживает и поощряет: - **ADR-журнал** со статусами `proposed/accepted/superseded` (правило 1). - **Vision one-pager + дизайн-столпы (3–8).** Столпы — фильтр фич: «служит столпу? нет → режем». Живут в `10-vision/`. Их пишет Макс (я оформляю), см. `references/authoring-artifacts.md`. - **Mermaid-диаграммы петель.** Core loop / экономика забега — флоучартом в странице, не стеной текста. - **frontmatter-статусы + Dataview-дашборд** готовности (правило 4). ## Структура (Фаза 1 выполнена) Папки-кластеры (Johnny.Decimal-lite: номер на уровне ПАПКИ, порядок файлов — `order`): ``` docs/wiki/gdd/ 00-meta/ index(MOC)·journal-adr·roadmap·open·glossary·legacy 10-vision/ (⊕vision·⊕pillars)·concept·lore·guildmaster·difficulty-skill 20-combat/ combat-system·stats·effects 30-run-meta/ injuries-mettle·procedural-lore·meta-progression·events-minigames 40-content/ relics-overview·items-banners·authoring/·items/ relics/ roster/ enemies/(+species/) — карточки контента, ЖИВУТ В КОРНЕ vault (решено 2026-07-26: переезд в 40-content/ отклонён — ломает сотни ссылок ради стройности) 50-modes-ux/ multiplayer·controls research/ depth·randomness-appendix·autobattlers/ ``` - Имена файлов — **латинские слаги** (`combat-system.md`), человекочитаемое имя — в `title:` кириллицей (Obsidian/Quartz показывают title). `⊕` — ещё не заведено. - **Сделано 2026-07-26 (большой аудит):** карточки на слагах; `enemies/factions/` → `enemies/species/`; поле `roles` упразднено (оси Role=`combat_class` / `playstyle` / `mechanics`); шапки полные у всех 114 доков, линт `scripts/check-wiki-frontmatter.ps1` в CI **роняет сборку** при нарушении; чекер ссылок видит якори и выходы за vault. - **Осталось:** Quartz Explorer `sortFn` по `order` (untested TS, нужен билд сайта). Не запускать Фазу 2 без «да». - **agent-friendly:** MOC-навигация (живые индекс-страницы) + Templater-шаблоны карточек. `docs/AGENTS.md` НЕ заводим (работаем 90% через этот скилл; дубль правил = рассинхрон). ## Процедура записи ГД-решения 1. Макс принял решение → запись в `0.7` (журнал): сессия-дата (H2), тема (H3), строка `# | Решение | Причина`, статус `accepted`. Замещает старое? — старое `superseded` + ссылка, не стирать. **HARD: формулировка Макса идёт в запись дословно** — блок-цитата под строкой решения, с провенансом `(дата, сессия <8 симв>)`. Мой пересказ — в колонке «Решение», его слова — в цитате; не сливать. Опечатки и пунктуацию не править, сокращать только многоточием, середину фразы не выбрасывать молча. Причина: пересказ невидим, и расхождение всплывает через месяц уже как «правда». Цитату брать не из своего резюме, а из архива — `Transcripts.ps1 quote "фрагмент"` (скилл `xgaida-x-nixi-transcripts`). 2. **Разнести** в тот же заход: обновить все затронутые канон-главы; в журнале указать куда. 3. Если тема была в `0.1 Roadmap`/`open` — вычеркнуть/перенести оттуда. 4. Сверить термины с глоссарием; новые — сперва в `0.4`. 5. Обновить `status`/`updated` во frontmatter затронутых доков. ## Чеклист сдачи ГД-задачи - [ ] Принятое решение — в журнале `0.7` (дата + причина + `accepted`); старое, если заместилось, помечено `superseded`, не затёрто - [ ] Слова Макса в записи стоят дословно с провенансом; цитата взята из архива, а не из моего резюме; сокращения — многоточием - [ ] Решение разнесено во все канон-дома; в журнале указано куда (нет «решено-но-не-разнесено») - [ ] Термины сверены с глоссарием; EN-канон у сущностей; синонимы не расплодились - [ ] У затронутых доков актуальны `status`/`updated`; порядок — через `order`, не имя - [ ] Своё предложение помечено `proposed` **в `open.md`**, не выдано за принятое и не оставлено в карточке - [ ] Тронутая карточка контента несёт только механику: провенанс, долги реализации и баланс-флаги уехали по маршруту правила 5, внизу стоит блок ссылок на дома - [ ] Ссылки целы (`[[wikilinks]]`/markdown); при переносе файла — починены - [ ] Loc-ключи для нового текста заложены по проектному правилу (RU заполнен) ## Справочные файлы (читать по надобности) - `references/decision-journal-adr.md` — формат ADR, статусы, superseded, шаблон записи, разнос по канону. Читать перед записью решения. - `references/structure-and-frontmatter.md` — кластеры-папки, слаги + `title`, `order`, статусы, Dataview-дашборд, механика переименования без поломки ссылок, план миграции, MOC. - `references/terminology-and-canon.md` — глоссарий, Справочник тегов, EN-канон, карта канон-домов (какой факт где живёт), связь с кодом/id. - `references/authoring-artifacts.md` — vision one-pager, дизайн-столпы, Mermaid-петли, Templater-шаблоны; как писать сильный ГД-документ.