dfg-inc/praxis-ba/ba-onboard

BA Onboard — перевод существующего проекта на флоу

Берёт живой кодовой проект без BA-артефактов и реверсит из него контекст. Работа смещена со «спросить» на «извлечь из кода»: документируем реальность, не изобретаем требования.

Вход: доступ к репозиторию проекта + slug. Выход: слой вокруг канона, восстановленный из кода (shared/*, glossary.md, project.md, as-is.md), и выбранный первый срез, переданный в praxis-ba:capture-cr.

Термины (строго в этом значении). Область — функциональная часть системы, кандидат на документирование (Shopping, Tasks, Auth). Срез — одна область, выбранная под документирование сейчас: один срез → один эпик канона. Область становится срезом в момент выбора на Шаге 6.

<HARD-GATE> (1) Не документируй всю систему сразу — только по срезам, начиная с одного. (2) Реверс фиксирует то, что есть; где из кода видно что, но не видно зачем — ставь [NEEDS CLARIFICATION], а не догадку. (3) Не записывай файлы, пока человек не одобрил реверс-контекст и выбранный срез. (4) Не пиши в canon/ — ни строки; требования рождаются только из CR через скиллы praxis-ba. </HARD-GATE>

Checklist

Строго по порядку, задача на каждый шаг:

1. Скелет — если слоя вокруг канона нет, разверни его скиллом ba-scaffold
2. Инвентаризация — стек, структура, области + код-якоря каждой области
3. Реверс `shared/` — data-model, integrations, rbac, nfr из кода
4. glossary + project.md — термины и суть продукта
5. AS-IS карта — что есть и что делает, по факту (грубо, 1–2 строки на область)
6. Выбери первый срез — одну область, не всё сразу
7. Перечисли поверхность среза — praxis-ba code-surface-scan --root <code> --anchors … (не на память; Explore только как запасной оркестратор)
8. Валидируй с человеком — построчно по выводам, не штампом
9. Запиши артефакты контекста
10. Передай срез в канон — praxis-ba:capture-cr

Шаг 1 — Скелет

Если папки inputs/, shared/, diagrams/ и project.md ещё нет — разверни слой скиллом `ba-scaffold`, он единственный источник истины по составу скелета. Не дублируй список здесь.

Канон: если в папке нет .ba/, перед передачей среза в praxis-ba:capture-cr выполни скилл `ba-init` (он создаёт машинные файлы канона и черновик vision.md, ничего не перезаписывая).

Отличие онбординга: ядро project.md и shared/* не выспрашиваются вопросами, а восстанавливаются из кода на Шагах 2–5. На Шаге 1 достаточно пустого скелета. Существующее не перезаписывай.

Шаг 2 — Инвентаризация

Карта проекта, без углубления в детали:

• Стек — языки, фреймворки, БД (по манифестам: package.json, requirements, go.mod, pom.xml и т.п.)
• Структура — основные папки/модули, точки входа
• Области (домены) — на какие функциональные части бьётся система (по модулям, роутам, экранам). Будущие срезы, то есть будущие эпики.
• Код-якоря области — для КАЖДОЙ области конкретные файлы-источники: роуты/контроллеры backend и экраны/компоненты frontend. Это «поверхность», которую обойдёт Шаг 7. Якоря — грубо (где лежит), без разбора содержимого.

Выведи карту областей списком (область → код-якоря) — она нужна на Шагах 6–7.

Шаг 3 — Реверс shared/ (из кода)

Заполни справочники по исходникам: код, конфигурации, схемы БД. Где видно что, но не зачем → [NEEDS CLARIFICATION].

Уровень BA, не код. Извлекай бизнес-смысл, не копируй реализацию: сущность и её поля — да; тип колонки, индекс, движок БД — нет.

`shared/nfr.md` — это каталог, на который потом ссылаются требования канона. Каждая восстановленная НФР получает устойчивый идентификатор: ba-lint проверяет, что ссылка из требования ведёт на существующую запись каталога. Заводи запись даже там, где значение неизвестно — со значением [NEEDS CLARIFICATION], но с идентификатором.

Регуляторные требования из кода не реверсятся. Юрисдикция и применимые регуляции — блок «Регуляторный контур» в project.md, его объявляет человек. Из кода восстановимы только технические НФР.

Шаг 4 — glossary + project.md

• `glossary.md` — термины из имён сущностей, доменных модулей, доков. Предлагаешь ты, утверждает человек.
• `project.md` — суть продукта, пользователи, цель. Извлеки из README/доков/структуры; чего нет — спроси парой вопросов или [NEEDS CLARIFICATION].

Названия технологий в глоссарий не тащи — им место в тех-словаре, и в требованиях они не употребляются.

Шаг 5 — AS-IS карта

Снимок существующего поведения по факту. Файл: <проект>/as-is.md по шаблону ${CLAUDE_PLUGIN_ROOT}/templates/layer/as-is.md. Это снимок реальности, не замысел.

AS-IS претендует только на «что есть», не на «зачем». Намерение из кода невосстановимо — его определит человек на элиситации. Поэтому каждая строка размечается честно:

• `[факт]` — прямо наблюдаемо (есть эндпоинт, кнопка делает X) + код-якорь как доказательство.
• `[вывод]` — твоя интерпретация смысла операции; ставь уверенность выс./сред./низк., она подлежит валидации человеком на Шаге 8.
• `[❓]` — поведение видно, смысл неясен → [NEEDS CLARIFICATION], не догадка.

Иерархия доказательств для смысла (код — самый слабый): тесты → документация → наблюдение работающей системы → вывод из кода. Где смысл важен и неочевиден — ищи тест или док, а не трактуй код.

Гранулярность: карта областей — грубо (1–2 строки); детальная размеченная таблица — только для выбранного среза (Шаг 7). Расхождения код↔доки помечай ⚠️, но не чини здесь.

Шаг 6 — Выбор первого среза

Не документируй всё сразу: это выброшенная работа (контекст устареет) и паралич онбординга. Предложи человеку одну область под первый эпик по приоритету:

• та, что вот-вот меняется (ближайшая работа), или
• самая ценная для бизнеса, или
• хуже всех задокументированная при высоком риске.

Один срез → один эпик. Остальные области ждут очереди.

Шаг 7 — Перечисление поверхности среза

Зачем. Чтение кода агентом — это выборочный просмотр, а не сплошной разбор: работающая функция в неочевидном месте (отдельный эндпоинт, кнопка в компоненте) может быть пропущена. Так уже случилось — функция «добавить из истории» в области Shopping была в коде и работала, но в AS-IS не попала. Решение — не полагаться на «прочитал и заметил», а перечислить поверхность детерминированно.

Только для выбранного среза, не для всей системы.

По код-якорям выбранной области (из Шага 2):

1. Запусти `ba-code-surface-scan` — в изолированном контексте (агент Explore, только чтение), передав имя области и её код-якоря. Он вернёт два буквальных списка: backend-роуты и frontend-действия, без интерпретации смысла.
2. Сопоставь каждую строку с поведением — уже в своём контексте разберись, что операция делает по факту, на BA-уровне. Это сырьё для будущих требований.
3. Пометь несвязанные операции — операция есть в списке, но ни один очевидный сценарий её не объясняет → [NEEDS CLARIFICATION].
4. Учти пробелы из отчёта — якорь помечен как не найденный/нечитаемый (⚠️) → область не покрыта, скажи об этом человеку явно.

Результат — таблица «эндпоинт/действие → поведение» по области. Идёт на Шаг 8 и далее в канон как сырьё для CR.

❗ Полнота важнее краткости: список покрывает все операции области, а не репрезентативную выборку.

Шаг 8 — Валидация с человеком

Покажи результат реверса целиком: контекст (shared/*, glossary.md, project.md, AS-IS), предложенный первый срез с обоснованием приоритета и таблицу поверхности из Шага 7.

Это валидация, а не штамп. Реверс производит черновик-гипотезу; фактом её делает подтверждение человека. Поэтому одобрение построчное по выводам:

• по каждой строке [вывод] — человек подтверждает (✅), правит или переводит в [❓];
• строки [факт] достаточно бегло сверить;
• неподтверждённый вывод остаётся `[NEEDS CLARIFICATION]`, молча фактом не становится.

До одобрения файлы не записываются (HARD-GATE 3).

Шаг 9 — Запись артефактов

После одобрения запиши контекст: shared/*, glossary.md, project.md, as-is.md. Незакрытые места оставь как [NEEDS CLARIFICATION].

Прогони третий проход `ba-lint` — связность слоя вне канона. Первые два прохода на этом шаге проверять нечего: канона ещё нет, он появится после первого CR. Ссылки внутри нового слоя должны быть целыми до того, как на них начнут ссылаться требования.

Шаг 10 — Передача среза в канон

Требование не рождается из реверса напрямую — только из CR. Порядок:

1. `praxis-ba:capture-cr` — заводи запрос на первичный объём среза. Тело запроса — то, что дал реверс: область, её поверхность, подтверждённые выводы AS-IS.
2. `praxis-ba:grill-cr` — интервью по объёму: закрываются [NEEDS CLARIFICATION], определяется точка входа.
3. `ba-plan-slice` — нарезка объёма на истории и сборка impact-набора до подтверждения CR.
4. `praxis-ba:shape-requirement` — по одному impact-entry за раз.

Пометка происхождения — в тексте эпика, не во frontmatter. У движка своя схема полей, и fmt посторонние поля из frontmatter вычищает. Поэтому «этот объём восстановлен из кода, а не задан документом» пиши разделом в index.md эпика — с указанием, какие выводы ратифицированы человеком, а какие остались [NEEDS CLARIFICATION]. Это важно на приёмке: «так задумано» и «так исторически вышло» — разные основания.

❌ Не заводи эпик на всю систему. Один срез за раз.

Правила

• Документируй реальность, не изобретай — источник истины здесь код, не воображение.
• По срезам, не океан — один эпик = одна область; остальное ждёт.
• Поверхность среза перечисляют, а не вспоминают — детерминированно, полнота важнее краткости, иначе рабочая фича выпадет.
• Реверс фиксирует *что* → `[NEEDS CLARIFICATION]` про *зачем* — бизнес-намерение из кода не видно.
• Факт и вывод раздельно; вывод ратифицирует человек — иначе он остаётся [NEEDS CLARIFICATION].
• Для смысла предпочитай тесты и доки коду — иерархия доказательств выше.
• WHAT/WHY, не HOW — технологии и реализацию в артефакты не переноси.
• Агент предлагает, человек утверждает — для сущностей, ролей, терминов, выбора среза.
• В `canon/` не писать — только через скиллы praxis-ba.

Incremental onboard / dedupe (WBS 1.3.3)

Когда канон уже частично заполнен (повторный заход, второй срез):

1. Инвентаризация существующих id — praxis-ba status --repo <canon> и список cr/, epics/*/E*-FR*.md; не создавай CR/FR с тем же смыслом под новым id.
2. Поверхность — praxis-ba code-surface-scan --root <code> --accept-scan при первом заходе; повторно --incremental (новые/изменённые fingerprints). --canon <canon> скрывает операции, уже упомянутые в существующих CR/FR.
3. Dedupe перед capture-cr — сравни новый срез с ### Delivers / traces_to существующих страниц; при совпадении поверхности — amend через существующий CR (impacts.amends), не spawn дубликата.
4. Инкремент среза — новый эпик только если область новая; иначе расширяй текущий epic новыми FR после подтверждённого CR.
5. Не перезаписывай confirmed vision / baselined requirements. praxis-ba onboard-context --init пропускает существующие файлы слоя; канон не трогает.