diff --git a/README.md b/README.md index 1ce190e..d3c691f 100644 --- a/README.md +++ b/README.md @@ -123,6 +123,7 @@ an explicit `adapted-from` marker in its frontmatter. | `writing-skills` | `adapted-from: obra/superpowers @ 6.2.0` (MIT) — TDD-for-skills core + ideya 8 self-skill-authoring | | `web-search` | `author: ours` — search_web tool (pi-extension) + policy: when to search, «без поиска» session-off | | `review-subagent` | `author: ours` — review_subagent tool (pi-extension): clean-context review by your own model, optional `model` override | +| `report-mappa-issue` | `author: ours` — TEMPORARY stopgap: mappa deviation reporting (mail to `mappa` + `.workshop`) while the service is unstable; retire when stabilized | | all other `skills/*` | `author: ours` | Adaptation policy: a clone is rewritten to our conventions (`.tasks/` boards, diff --git a/dist/report-mappa-issue.skill b/dist/report-mappa-issue.skill new file mode 100644 index 0000000..0b50c1e Binary files /dev/null and b/dist/report-mappa-issue.skill differ diff --git a/skills/report-mappa-issue/SKILL.md b/skills/report-mappa-issue/SKILL.md new file mode 100644 index 0000000..fdd46fb --- /dev/null +++ b/skills/report-mappa-issue/SKILL.md @@ -0,0 +1,113 @@ +--- +name: report-mappa-issue +author: ours +version: 0.1.0 +description: > + Use when working with mappa (MCP tools `mcp__mappa__*`, HTTP-роуты, скилы на + mappa) and anything deviates from the expected workflow: 500/5xx, «entity not + found» для id, который должен существовать, неожиданная форма ответа, + таймауты, молчаливые сбои, неверный статус, нестабильность. Report it by + mail to `mappa` AND `.workshop` — never swallow, never only-local-log, never + only in-chat. TEMPORARY skill: active while mappa is unstable; retire when + stabilized. Triggers: «маппа отдала 500», «entity not found», «неожиданный + ответ от mappa», «mappa вернула», "mappa returned 500", "entity not found", + unexpected mappa response. +--- + +# report-mappa-issue + +Любое отклонение от ожидаемого mappa-воркфлоу репортится **почтой в `mappa` +и `.workshop`** — немедленно, с evidence. Не глотать, не прятать в локальный +лог, не откладывать «до сборника». + +> ⚠️ **TEMPORARY (временный скил):** действует, пока mappa нестабильна. Это +> stopgap для сбора сигналов к стабилизации. Когда mappa стабилизируется +> (неделя без репортов) — скил отзывается: репорты становятся обычными +> баг-тасками. Владелец решения об отзыве — workshop. + +## When to use + +Репортить, когда в ходе работы с mappa произошло **любое** из: + +- **5xx / 500 / 502** на любом вызове (`task_*`, `wiki_*`, `inbox_*`, `entity_*`, + `admin_*`, `graph_*`, HTTP-роуты). +- **«Entity not found» / 404** для id/ref, который **должен** существовать + (знаешь, что создавал; видишь в свежем ответе; ссылается другое письмо/таска). +- **Неожиданная форма ответа** — поля не совпадают с документированными, + пустой `rows` где ожидались данные, новый/неожиданный тип в ответе. +- **Таймауты / зависания** вызова. +- **Молчаливый сбой** — вызов «успешен», но эффекта нет (таска не создалась, + письмо не ушло, статус не поменялся). +- **Ретрай сработал** — даже если повторный вызов прошёл: сама нестабильность + — сигнал для стабилизации (пометь `retry: resolved`). +- **Неверный/неожиданный статус** сущности, рассинхрон борда и реальности. + +**Ретраи допустимы** (1–2 с паузой), но репорт — независимо от исхода ретрая: +случай 500 → репорт; случай 500→ретрай→ок → репорт с `retry: resolved`. + +## When NOT to use + +- **Ожидаемый 404** — сущность действительно не существует и не должна + (никогда не создавалась; удалена по дизайну). Проверь перед репортом, что + сущность обязана была быть. +- **Документированные известные ограничения** (например, «verify на проде + невозможен по дизайну», «прод stale до редеплоя» — если это задокументировано + и известно команде mappa). +- **Отклонения НЕ от mappa** — VDS/docker (→ using-vds-ops), projects-meta кэш + (документированная сталезность), провайдеры моделей. Только mappa. +- **Уже зарепорченный тот же инцидент** — не дублируй (см. Dedup). + +## Core pattern — репорт + +Каждый вызов: `mcp__mappa__inbox_send` в **оба** адреса (`mappa` и `.workshop`, +адреса из адресной книги `~/projects/.wiki/concepts/projects-address-book.md`), +`from` = своё имя папки. Формат письма: + +``` +Subject: [mappa-issue] <симптом> @ <тул/эндпоинт> (<дата>) + +Body: +- Expected: <что должно было произойти по воркфлоу/докам> +- Actual: <ошибка/статус/ответ — текст сообщения или короткий сниппет> +- Call: <тул + ключевые параметры / эндпоинт + project> +- Retry: <сработал ли ретрай, сколько попыток> +- Recurrence: <первый раз / повторяется — сколько раз за сессию> +- Context: <проект, сессия, какой флоу шёл> +``` + +Одно письмо = **один инцидент** (симптом × эндпоинт). Рекуррентность — в том же +письме (`recurrence: 5 раз за 2 часа`), не новый репорт на каждый вызов. + +## Common mistakes / rationalizations + +| Рационализация | Реальность | +|---|---| +| «Mappa упала — письмо не дойдёт, зачем писать» | Письмо — сущность в Mappa (карв-аут, без лиза). При оживлении сервиса оно будет в инбоксе получателя. Пиши всегда. | +| «Расскажу человеку в чате» | Человек не всегда в сессии, команда mappa чат не видит. Письмо — durable и кросс-сессионно. | +| «Запишу в локальный лог» | Локальный лог не виден команде mappa. Цель репорта — видимость у получателей. (Локальная запись — дополнительно, не вместо.) | +| «Ретрай сработал — значит ок» | Нестабильность — сам по себе сигнал. Репорть с `retry: resolved`. | +| «Это мелочь, не буду спамить» | Пока mappa нестабильна — любой сигнал материал для стабилизации. Dedup защищает от спама, не молчание. | +| «Соберу несколько и отпишусь разом» | Первое вхождение — немедленно. Рекуррентность докидывай в то же письмо. | +| «Это наверняка уже известно mappa» | Неизвестно, пока не зарепорчено. Репорт — это и есть способ сделать известным. | + +## Red flags — STOP + +- Поймал ошибку mappa и продолжил молча (без репорта). +- Записал только локально / сказал только в чате — письма нет. +- Пропустил «entity not found», не проверив, должен ли id существовать. +- Отложил репорт «на потом» без письма и без таски. +- Зарепортил, но не в оба адреса (`mappa` и `.workshop`). + +## Cross-agent + +Канал — mappa inbox (`inbox_send` / `inbox.monitor`), общий для всех агентов +(pi: `mcp__mappa__inbox_send`; Claude Code: те же MCP-тулы; headless — то же). +Адресация — строго из адресной книги (`inter-session-messaging` канон). + +## Out of scope + +- **Не чинит mappa** — диагностика/починка сервиса отдельно; скил только + репортит. (Глубокий диагноз — `diagnosing-bugs` / `using-vds-ops` для инфры.) +- **Не репортит чужие сервисы** — только отклонения от mappa-воркфлоу. +- **Не заменяет** `inter-session-messaging` (механика отправки — там, этот скил + задаёт политику «что считать инцидентом»).