diff --git a/skills/report-mappa-issue/SKILL.md b/skills/report-mappa-issue/SKILL.md index fdd46fb..c157164 100644 --- a/skills/report-mappa-issue/SKILL.md +++ b/skills/report-mappa-issue/SKILL.md @@ -1,113 +1,117 @@ --- name: report-mappa-issue author: ours -version: 0.1.0 +version: 0.2.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», «неожиданный + Use when working with mappa (MCP tools `mcp__mappa__*`, HTTP routes, mappa + skills) and anything deviates from the expected workflow: 500/5xx, "entity + not found" for an id that must exist, unexpected response shape, timeouts, + silent failures, wrong status, instability. 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 (bilingual): «маппа отдала 500», «entity not found», «неожиданный ответ от mappa», «mappa вернула», "mappa returned 500", "entity not found", - unexpected mappa response. + "unexpected mappa response". --- # report-mappa-issue -Любое отклонение от ожидаемого mappa-воркфлоу репортится **почтой в `mappa` -и `.workshop`** — немедленно, с evidence. Не глотать, не прятать в локальный -лог, не откладывать «до сборника». +Any deviation from the expected mappa workflow is reported **by mail to `mappa` +and `.workshop`** — immediately, with evidence. Never swallow, never hide it in +a local log, never postpone "until a digest". -> ⚠️ **TEMPORARY (временный скил):** действует, пока mappa нестабильна. Это -> stopgap для сбора сигналов к стабилизации. Когда mappa стабилизируется -> (неделя без репортов) — скил отзывается: репорты становятся обычными -> баг-тасками. Владелец решения об отзыве — workshop. +> ⚠️ **TEMPORARY skill:** active while mappa is unstable. It is a stopgap for +> collecting signals toward stabilization. When mappa stabilizes (a week +> without reports) — this skill is retired: reports become ordinary bug tasks. +> The owner of the retirement decision is workshop. ## When to use -Репортить, когда в ходе работы с mappa произошло **любое** из: +Report when, during work with mappa, **any** of the following happens: -- **5xx / 500 / 502** на любом вызове (`task_*`, `wiki_*`, `inbox_*`, `entity_*`, - `admin_*`, `graph_*`, HTTP-роуты). -- **«Entity not found» / 404** для id/ref, который **должен** существовать - (знаешь, что создавал; видишь в свежем ответе; ссылается другое письмо/таска). -- **Неожиданная форма ответа** — поля не совпадают с документированными, - пустой `rows` где ожидались данные, новый/неожиданный тип в ответе. -- **Таймауты / зависания** вызова. -- **Молчаливый сбой** — вызов «успешен», но эффекта нет (таска не создалась, - письмо не ушло, статус не поменялся). -- **Ретрай сработал** — даже если повторный вызов прошёл: сама нестабильность - — сигнал для стабилизации (пометь `retry: resolved`). -- **Неверный/неожиданный статус** сущности, рассинхрон борда и реальности. +- **5xx / 500 / 502** on any call (`task_*`, `wiki_*`, `inbox_*`, `entity_*`, + `admin_*`, `graph_*`, HTTP routes). +- **"Entity not found" / 404** for an id/ref that **must** exist (you know you + created it; you see it in a fresh response; another letter/task references it). +- **Unexpected response shape** — fields don't match the documented ones, + empty `rows` where data was expected, a new/unexpected type in the response. +- **Timeouts / hangs** on a call. +- **Silent failure** — the call "succeeded" but had no effect (task not + created, letter not delivered, status unchanged). +- **Retry worked** — even if the repeated call succeeded: the instability + itself is a signal for stabilization (mark `retry: resolved`). +- **Wrong/unexpected entity status**, board vs reality desync. -**Ретраи допустимы** (1–2 с паузой), но репорт — независимо от исхода ретрая: -случай 500 → репорт; случай 500→ретрай→ок → репорт с `retry: resolved`. +**Retries are allowed** (1–2 with a pause), but the report happens regardless +of the retry outcome: case 500 → report; case 500 → retry → ok → report with +`retry: resolved`. ## When NOT to use -- **Ожидаемый 404** — сущность действительно не существует и не должна - (никогда не создавалась; удалена по дизайну). Проверь перед репортом, что - сущность обязана была быть. -- **Документированные известные ограничения** (например, «verify на проде - невозможен по дизайну», «прод stale до редеплоя» — если это задокументировано - и известно команде mappa). -- **Отклонения НЕ от mappa** — VDS/docker (→ using-vds-ops), projects-meta кэш - (документированная сталезность), провайдеры моделей. Только mappa. -- **Уже зарепорченный тот же инцидент** — не дублируй (см. Dedup). +- **Expected 404** — the entity genuinely does not exist and should not + (never created; deleted by design). Before reporting, check that the entity + was required to exist. +- **Documented known limitations** (e.g. "verify on prod is impossible by + design", "prod is stale until redeploy" — if documented and known to the + mappa team). +- **Deviations NOT from mappa** — VDS/docker (→ using-vds-ops), projects-meta + cache (documented staleness), model providers. Only mappa. +- **The same incident already reported** — don't duplicate (see Dedup). -## Core pattern — репорт +## Core pattern — the report -Каждый вызов: `mcp__mappa__inbox_send` в **оба** адреса (`mappa` и `.workshop`, -адреса из адресной книги `~/projects/.wiki/concepts/projects-address-book.md`), -`from` = своё имя папки. Формат письма: +Each call: `mcp__mappa__inbox_send` to **both** addresses (`mappa` and +`.workshop`, addresses from the address book +`~/projects/.wiki/concepts/projects-address-book.md`), `from` = your own +folder name. Letter format: ``` -Subject: [mappa-issue] <симптом> @ <тул/эндпоинт> (<дата>) +Subject: [mappa-issue] @ () Body: -- Expected: <что должно было произойти по воркфлоу/докам> -- Actual: <ошибка/статус/ответ — текст сообщения или короткий сниппет> -- Call: <тул + ключевые параметры / эндпоинт + project> -- Retry: <сработал ли ретрай, сколько попыток> -- Recurrence: <первый раз / повторяется — сколько раз за сессию> -- Context: <проект, сессия, какой флоу шёл> +- Expected: +- Actual: +- Call: +- Retry: +- Recurrence: +- Context: ``` -Одно письмо = **один инцидент** (симптом × эндпоинт). Рекуррентность — в том же -письме (`recurrence: 5 раз за 2 часа`), не новый репорт на каждый вызов. +One letter = **one incident** (symptom × endpoint). Recurrence goes in the same +letter (`recurrence: 5 times in 2 hours`), not a new report per call. ## Common mistakes / rationalizations -| Рационализация | Реальность | +| Rationalization | Reality | |---|---| -| «Mappa упала — письмо не дойдёт, зачем писать» | Письмо — сущность в Mappa (карв-аут, без лиза). При оживлении сервиса оно будет в инбоксе получателя. Пиши всегда. | -| «Расскажу человеку в чате» | Человек не всегда в сессии, команда mappa чат не видит. Письмо — durable и кросс-сессионно. | -| «Запишу в локальный лог» | Локальный лог не виден команде mappa. Цель репорта — видимость у получателей. (Локальная запись — дополнительно, не вместо.) | -| «Ретрай сработал — значит ок» | Нестабильность — сам по себе сигнал. Репорть с `retry: resolved`. | -| «Это мелочь, не буду спамить» | Пока mappa нестабильна — любой сигнал материал для стабилизации. Dedup защищает от спама, не молчание. | -| «Соберу несколько и отпишусь разом» | Первое вхождение — немедленно. Рекуррентность докидывай в то же письмо. | -| «Это наверняка уже известно mappa» | Неизвестно, пока не зарепорчено. Репорт — это и есть способ сделать известным. | +| "Mappa is down — the letter won't arrive, why write" | A letter is an entity in Mappa (carve-out, no lease). When the service revives, it will be in the recipient's inbox. Always write. | +| "I'll tell the human in chat" | The human is not always in session; the mappa team doesn't see chat. A letter is durable and cross-session. | +| "I'll write it in the local log" | The local log is invisible to the mappa team. The goal of the report is visibility for recipients. (Local recording is extra, not instead.) | +| "The retry worked — so it's fine" | The instability itself is a signal. Report with `retry: resolved`. | +| "It's a small thing, I won't spam" | While mappa is unstable — any signal is material for stabilization. Dedup protects against spam, silence does not. | +| "I'll collect several and report at once" | First occurrence — immediately. Recurrence gets appended to the same letter. | +| "Mappa surely already knows this" | Unknown until reported. The report is exactly how it becomes known. | ## Red flags — STOP -- Поймал ошибку mappa и продолжил молча (без репорта). -- Записал только локально / сказал только в чате — письма нет. -- Пропустил «entity not found», не проверив, должен ли id существовать. -- Отложил репорт «на потом» без письма и без таски. -- Зарепортил, но не в оба адреса (`mappa` и `.workshop`). +- Caught a mappa error and silently continued (no report). +- Recorded only locally / said only in chat — no letter. +- Skipped "entity not found" without checking whether the id must exist. +- Postponed the report "for later" without a letter and without a task. +- Reported but not to both addresses (`mappa` and `.workshop`). ## Cross-agent -Канал — mappa inbox (`inbox_send` / `inbox.monitor`), общий для всех агентов -(pi: `mcp__mappa__inbox_send`; Claude Code: те же MCP-тулы; headless — то же). -Адресация — строго из адресной книги (`inter-session-messaging` канон). +Channel — mappa inbox (`inbox_send` / `inbox.monitor`), shared by all agents +(pi: `mcp__mappa__inbox_send`; Claude Code: the same MCP tools; headless — the +same). Addressing strictly from the address book (`inter-session-messaging` +canon). ## Out of scope -- **Не чинит mappa** — диагностика/починка сервиса отдельно; скил только - репортит. (Глубокий диагноз — `diagnosing-bugs` / `using-vds-ops` для инфры.) -- **Не репортит чужие сервисы** — только отклонения от mappa-воркфлоу. -- **Не заменяет** `inter-session-messaging` (механика отправки — там, этот скил - задаёт политику «что считать инцидентом»). +- **Does not fix mappa** — service diagnosis/repair is separate; this skill + only reports. (Deep diagnosis — `diagnosing-bugs` / `using-vds-ops` for + infra.) +- **Does not report other services** — only deviations from the mappa workflow. +- **Does not replace** `inter-session-messaging` (the send mechanics live + there; this skill defines the policy "what counts as an incident").