| name | ui-action-observability |
| description | Use for shipped UI action journal, request correlation, WebSocket churn, or frontend observability work. |
UI Action Observability
What This Skill Does
Пакует repeatable workflow для shipped capability ui-action-observability: снять bounded UI journal bundle, связать его с request_id / ui_action_id на backend boundary и безопасно расширить instrumentation без поломки redaction-first contract.
When To Use
Используй, когда пользователь просит:
- "сними UI journal"
- "разбери frontend-инцидент через request_id/ui_action_id"
- "проверь, почему action сломался и как это связано с backend error"
- "добавь/исправь trackUiAction, request correlation или websocket observability"
- "проверь churn/reuse WebSocket"
Не используй для обычной UI-правки без observability/debug scope.
Primary Surfaces
- spec:
openspec/specs/ui-action-observability/spec.md
- frontend journal core:
frontend/src/observability/uiActionJournal.ts
- frontend wiring:
frontend/src/App.tsx
- shared HTTP correlation:
frontend/src/api/client.ts
- semantic confirm helper:
frontend/src/observability/confirmWithTracking.ts
- boundary capture:
frontend/src/components/ErrorBoundary.tsx
- realtime instrumentation example:
frontend/src/hooks/useWorkflowExecution.ts
- backend correlation + redaction:
orchestrator/apps/api_v2/observability.py
- debug export path:
debug/export-ui-journal.sh
Workflow
- Прочитай
docs/agent/RUNBOOK.md, docs/agent/VERIFY.md и DEBUG.md, если задача про runtime incident или export bundle.
- Для usage/debug сначала воспроизведи проблему на аутентифицированной frontend session.
- Сними bundle через
./debug/export-ui-journal.sh [url-pattern] или ./debug/eval-frontend.sh "JSON.stringify(window.__CC1C_UI_JOURNAL__?.exportBundle() ?? null, null, 2)".
- В bundle анализируй:
events[] для route/action/error chronology;
active_http_requests;
active_websockets_by_owner;
active_websockets_by_reuse_key;
recent_churn_anomalies.
- Для HTTP failure path сопоставь
request_id и ui_action_id из bundle с backend problem payload и server logs.
- Если меняешь instrumentation, сначала найди правильный boundary:
- route/global runtime hooks:
frontend/src/App.tsx
- form/modal/drawer confirms: platform shells и
confirmWithTracking.ts
- API request lifecycle:
frontend/src/api/client.ts
- render/runtime failures:
frontend/src/components/ErrorBoundary.tsx
- realtime lifecycle: конкретный hook/store, по примеру
frontend/src/hooks/useWorkflowExecution.ts
- server-side correlation/redaction:
orchestrator/apps/api_v2/observability.py
Implementation Rules
- Instrument only semantic events. Не добавляй raw DOM/session replay stream.
- Для explicit operator actions используй
trackUiAction(...) или confirmWithTracking(...).
- Не прокидывай в journal сырые form values; оставляй только whitelisted metadata.
- Не ломай transport contract: frontend должен передавать
X-Request-ID и X-UI-Action-ID, backend должен возвращать их в headers/problem payloads на fail-closed paths.
- Для WebSocket instrumentation фиксируй
owner, reuseKey, channelKind, socketInstanceId, lifecycle outcome и churn signal.
- Учитывай shipped guardrail: production callsites
trackUiAction должны оставаться sync или microtask-detached; не вводи произвольные async handlers без обновления supporting logic и tests.
Validation
- frontend journal/redaction/unit scope:
cd frontend && npx vitest run src/observability/__tests__/uiActionJournal.test.ts src/api/__tests__/client.observability.test.ts src/observability/__tests__/trackUiActionUsage.test.ts
- orchestrator correlation/redaction scope:
./scripts/dev/pytest.sh -q orchestrator/apps/api_v2/tests/test_problem_details_request_correlation.py
- для docs/routing изменений:
./scripts/dev/check-agent-doc-freshness.sh
- если трогал реальный UI flow, добавь runtime/export proof:
./debug/export-ui-journal.sh [url-pattern]
Success Criteria
- UI incident можно разобрать по одному bounded bundle без console archaeology
request_id / ui_action_id бьются между frontend bundle и backend payload/logs
- sensitive fields не попадают в journal и correlated error payloads
- validation покрывает изменённый boundary
Practical Jobs
Примеры:
- "Сними journal bundle после падения
/pools/runs и найди связанный backend request."
- "Добавь observability для нового confirm flow через
trackUiAction и проверь redaction."
- "Разбери, почему dedicated/shared WebSocket churn-ится, и покажи owner/reuse_key."