docs(skills): report-mappa-issue 0.1.0→0.2.0 — English translation, bilingual triggers (task:1086)

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] <symptom> @ <tool/endpoint> (<date>)
 
 Body:
-- Expected:   <что должно было произойти по воркфлоу/докам>
-- Actual:     <ошибка/статус/ответ — текст сообщения или короткий сниппет>
-- Call:       <тул + ключевые параметры / эндпоинт + project>
-- Retry:      <сработал ли ретрай, сколько попыток>
-- Recurrence: <первый раз / повторяется — сколько раз за сессию>
-- Context:    <проект, сессия, какой флоу шёл>
+- Expected:   <what should have happened per workflow/docs>
+- Actual:     <error/status/response — message text or a short snippet>
+- Call:       <tool + key parameters / endpoint + project>
+- Retry:      <did the retry work, how many attempts>
+- Recurrence: <first time / repeats — how many times this session>
+- Context:    <project, session, which flow was running>
 ```
 
-Одно письмо = **один инцидент** (симптом × эндпоинт). Рекуррентность — в том же
-письме (`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").