srekit

Скаффолдит SRE-артефакты через srekit и помогает заполнить секции по обсуждавшимся в сессии фактам.

Постмортем — отдельный навык srekit-postmortem, сюда не относится.

Когда использовать

• Пользователь хочет один из документов: investigation log, RFC, SLO, EBP, capacity plan, retro, on-call report, changelog, LICENSE.
• Пользователь явно упоминает srekit (но просит не постмортем).
• В обсуждении есть факты, которые логично оформить как один из этих артефактов (расследование → task, решение → rfc, договорённость о таргетах → slo). Повторяющийся фикс → отдельный навык srekit-runbook, не сюда.

Не использовать:

• Постмортем → навык srekit-postmortem.
• Произвольный markdown, который под srekit не подгоняется. Если шаблон не подходит — лучше написать руками, чем мучить шаблон.

Что делает srekit

Локальный CLI, генерирующий двуязычный (Русский (English)) markdown-каркас с YAML frontmatter из встроенных или пользовательских шаблонов. Содержимое секций срекит не пишет — он только готовит структуру. Наполнение — задача этого навыка.

Полный справочник по флагам каждой команды — в references/commands.md. Здесь — только то, что нужно для рабочего процесса.

Общие флаги для всех генераторов

--template FILE (one-shot подмена шаблона) есть только у license — у всех остальных генераторов был удалён в v0.22.0. Если пользователь просит «использовать наш шаблон» — это --templates-dir или templates init/upgrade, не --template.

Рабочий процесс

1. Убедись, что srekit доступен

srekit --version

Если команды нет — сообщи, что нужно поставить (brew install jtprogru/tap/srekit или go install github.com/jtprogru/srekit@latest), и остановись.

2. Выбери команду по интенту

Если интент «хочу задокументировать инцидент» — это всегда postmortem (отдельный навык srekit-postmortem). Команды для live-дока в srekit больше нет — для координации во время инцидента используется IM-инструмент (Slack/PagerDuty), не markdown-файл.

3. Собери обязательные поля

Минимум на команду:

Стратегия сбора:

• Что прозвучало в диалоге — подставь и подтверди одним сообщением со всеми полями сразу.
• Что не прозвучало — спроси одной репликой с 2-4 пунктами, не плоди отдельные вопросы.
• Не выдумывай timestamps, severity, имена сервисов. Если пользователь сказал «вчера» — переспроси дату/время.

--author/--email (где есть): порядок резолва внутри srekit — флаг → env (SREKIT_AUTHOR, SREKIT_EMAIL) → конфиг → git config user.name/email. Обычно достаточно ничего не передавать, и srekit сам подтянет из git config. Передавай явно, только если контекст диктует другое значение.

4. Определи путь к файлу

Правила в порядке приоритета:

1. Конвенция репозитория, если она видна. Поднимайся по дереву от CWD и ищи характерные каталоги:
   • docs/rfc/, docs/rfcs/, docs/adr/, docs/decisions/ → rfc
   • docs/slo/, slo/ → slo
   • docs/oncall/, oncall/ → oncall-report
   • investigations/, tasks/ → task
   • retros/, docs/retros/ → retro
   • корень репо → CHANGELOG.md, LICENSE
2. Срекит-дефолт, если конвенции нет. Дефолты по командам:
   • task → investigation-<slug>.md (директория из --path, по умолчанию CWD)
   • rfc → rfc-<slug>.md
   • slo → slo-<service>.md
   • ebp → ebp-<service>.md
   • capacity → capacity-<service>.md
   • retro → retro-<team>-<sprint>.md
   • oncall-report → oncall-<team>-<start>.md
   • changelog → CHANGELOG.md (в CWD)
   • license → stdout (если без --out)

Подводный камень с кириллицей в слаге. Сладжификатор srekit плохо работает с кириллическими title — например, -T "Зависание создания дисков" может дать почти пустой slug. Если title кириллический и ты полагаешься на дефолтное имя — лучше передай --out явно с латинским slug'ом. Для команд с <service>/<team> это меньше актуально, потому что service/team-имена обычно латиница.

Дата в имени файла, если по смыслу нужна — добавляй сам через --out. Срекит сам её в имя не вставляет (кроме oncall-report, где она в дефолте уже есть).

Если файл уже существует — спроси перед --force. Возможно, пользователь уже что-то начал.

5. Запусти srekit <cmd>

Один раз — финальной командой, не «попробуем dry-run, потом ещё раз». Покажи команду пользователю текстом перед запуском, чтобы он мог скорректировать поля.

Примеры (минимально-полные вызовы — флаги пропущены, если у них хороший дефолт):

srekit task -T "Tail latency on api-gw" --path ./investigations
srekit rfc -T "Adopt OpenTelemetry" --status proposed --out docs/rfc/rfc-otel.md
srekit slo --service api-gw --target 99.95% --window 30d --latency 200ms --out docs/slo/slo-api-gw.md
srekit ebp --service api-gw --out docs/slo/ebp-api-gw.md
srekit capacity --service api-gw --horizon 1y --out docs/capacity/capacity-api-gw.md
srekit retro --team platform --sprint 2026-W23 --out retros/retro-platform-2026-W23.md
srekit oncall-report --team platform --start 2026-06-01 --end 2026-06-07 --out docs/oncall/oncall-platform-2026-06-01.md
srekit changelog --out CHANGELOG.md
srekit license --type mit --out LICENSE

6. Наполни секции (если уместно)

После скаффолда сразу прочитай созданный файл и предложи наполнение — но только тех секций, по которым в сессии есть факты. Не выдумывай. По секциям, для которых данных нет, ставь GAP-маркер вида <!-- GAP: нужно уточнить у X -->.

Тип наполнения зависит от артефакта:

• task — Context / Hypothesis / Evidence / Findings / Action items. Из сессии хорошо ложатся Context (что исследуем и почему) и Evidence (что видим в логах/коммитах). Hypothesis — формулируй явно, как гипотезу, не как факт.
• rfc — Context / Decision / Alternatives / Consequences. Альтернативы — реально обсуждавшиеся, со ссылками на сообщения, если уместно. Не придумывай «вторую и третью альтернативу» для красоты.
• slo — таргеты, окно, бюджет, SLI-определения. Если SLI не обсуждали — GAP, не выдумывай PromQL.
• ebp — пороги (Yellow/Orange/Red), действия, исключения, эскалация. Если в команде есть существующая практика — отрази; нет — оставь шаблонные пороги и пометь GAP.
• capacity — baseline, growth assumptions, прогноз, scale triggers, risks. Цифры — только реальные из обсуждения или из систем мониторинга. Без данных — GAP.
• retro — Went well / What didn't / Action items. Тут наполнение в основном с команды на ретро, не у тебя; обычно достаточно скаффолда.
• oncall-report — pages, incidents, follow-ups. Если в сессии обсуждались конкретные алерты/инциденты недели — подтяни их.
• changelog — только структура; конкретные записи пользователь добавляет сам или через release-process. Не сочиняй фейковые [0.1.0] записи.
• license — наполнение не нужно, это финальный документ.

Общие правила наполнения (всех артефактов):

• Никаких личных имён. Пиши роли: oncall, SRE Lead, Platform team, Author. Имена выдают конкретных людей и токсичны в публичных артефактах.
• Blameless для postmortem-смежных артефактов: фокус на системе и процессе, не на действиях людей.
• GAP-маркеры вместо галлюцинаций. Лучше <!-- GAP: уточнить причину rollback'а у oncall -->, чем выдуманная фраза.
• Timestamps в UTC в теле артефактов (Timeline, Update log). Если в сессии MSK — конвертируй явно.
• Технические идентификаторы (SLO, SLI, PromQL, SEV-N, UTC) — английскими, как в шаблоне.

7. JSON / валидация (опционально)

Все генераторы поддерживают --json — выдаст структуру template-data, которую увидит шаблон (camelCase ключи). Полезно, если пользователь хочет встроить вызов в пайплайн:

srekit slo --service api-gw --target 99.95% --json | jq '.target'

--from FILE / --schema / --validate есть только у postmortem — для round-trip workflow (выдать JSON → отредактировать → отрендерить markdown обратно). У остальных генераторов этого нет, не предлагай.

Конфиг и пользовательские шаблоны

Если в репозитории есть templates_dir (конфиг ~/.config/srekit/config.yaml или env SREKIT_TEMPLATES_DIR) — srekit уже подтянет кастомные шаблоны автоматически. Передавать --templates-dir руками нужно только для one-shot подмены.

Если пользователь хочет завести командные шаблоны под git — это srekit templates init, дальше templates upgrade для синка с embedded-обновлениями. Подробно — srekit templates --help. В обычном flow генерации это не нужно — упоминай только если пользователь явно спросил про кастомизацию.

Антипаттерны

• Не запускать srekit от лица пользователя в директорию, которой нет (docs/rfc/, runbooks/, investigations/ и т.п.) — сначала mkdir -p. Срекит сам директорию не создаёт.
• Не передавать --template ни одной команде, кроме license — флаг убран в v0.22.0.
• Не вызывать --force не спросив, если файл уже есть. В половине случаев у пользователя там черновик.
• Не вызывать срекит дважды (один раз --dry-run, второй настоящий). Один вызов сразу финальный.
• Не наполнять секции выдуманными деталями. Лучше пустая секция с GAP, чем правдоподобная ложь — в инцидентных артефактах это опасно.
• Не делать постмортем этим навыком. Это srekit-postmortem.