UC-09: Issue Tracking -- TalkIDE Internal Docs

TalkIDE internal documentation

Persistentní mechanismus pro nahlašování problémů od agentů (primárně Mara) směrem k TalkIDE platform teamu. Nahrazuje stav, kdy Mara halucinovala “zalogovala jsem to pro tým TalkIDE” bez reálného propsání kamkoliv.

Vzniklo z deployu Stopa B 2026-05-13 — Mara řekla “Zalogovala jsem problém pro tým TalkIDE”, reálně neudělala nic. Token failure (registry write scope) se nezaregistroval, user musel diagnostikovat sám.

Design je univerzální (target = PLATFORM | PROJECT) — Phase 1 implementuje pouze PLATFORM target. Schema je připravené i pro budoucí user-app issue tracking (target=PROJECT, Phase 3).

Phase 1 — scope

UC ID	Název	Popis
UC-09001	Report Platform Issue	Mara tool `report_issue` → POST /api/issues — server-side context enrichment (K8s events, pod logs, conversation snippet, project state), rate limit 5/hod/session, dedup okno 10 min. Mara decision tree + severity/kind rubric.
UC-09002	Search Issues	Mara tool `search_issues` → GET /api/issues?target=&status=&query= — LIKE filtr nad title+description, scoped by reporter_user_id pro non-admin. Phase 3: rozšíření o `projectId` a `tenantScoped` params.
UC-09003	Comment Issue	Mara tool `comment_issue` → POST /api/issues/{id}/comments — komentář od Mara při opakovaném výskytu nebo doplňujícím kontextu.
UC-09004	Admin Triage Issue	Admin (Mirek, role `platform_admin`) → PATCH /api/issues/{id} — status transitions, CRITICAL severity override, resolution_note, duplicate-of link.

Phase 2 — scope (#87)

UC ID	Název	Popis
UC-09008	User Reports Platform Issue	User klikne na ”🐛 Nahlásit problém” ve Studio toolbaru → modal formulář → POST /api/issues s `X-Reporter-Agent: USER` + JWT. BE rozšiřuje reporter_agent whitelist o USER. Rate limit 5/hod/user-id. Dedup okno 10 min. Volitelný `X-Current-Project` header pro context enrichment.

Phase 3 — scope (#83, #91)

Phase 3 přidává target=PROJECT pro user-app issue tracking. Schema bylo připraveno v Phase 1 — Phase 3 doplňuje FK constraint (0020-add-project-fk-to-issues.xml), rozšiřuje reporter_agent whitelist o USER a přidává Studio UI.

UC ID	Název	Popis
UC-09005	Report Project Issue	Dual reporter: USER (Workspace tab modal → POST /api/issues) nebo MARA (tool call — sidecar resolvuje `project_id` z ctx, Mara ho nespecifikuje). Oba zapisují `target=PROJECT` se stejným shape. Validace: `project_id` required, tenant ownership check, cascade delete přes FK.
UC-09006	View Project Issues	PROJECT issues ve 3 lokacích: Workspace tab (per-project, `projectId` filter), Studio dashboard widget (cross-project top-5 preview + `total` z pagination envelope), dedikovaná list stránka `/studio/issues` (full cross-project list s filtry). Žádný separátní `/count` endpoint.
UC-09007	Mara Injects Open Issues	`MaraContextRenderer` injektuje OPEN/IN_PROGRESS PROJECT issues do CLAUDE.md jako sekci `# Open TODO issues` při každém startu/pokračování konverzace. Deterministické řazení `reported_at ASC, id ASC` pro Anthropic prompt cache. N+1 trick (LIMIT 21): ≤20 → plný list; 21 → 20 bullets + `> _and more than 20 more open issues_` bez COUNT(*).

Reporting authority

Pouze Mara má v Phase 1 přístup k Issue API. Kai/Eli o issues nic netuší — vracejí Maře normální errory, ona klasifikuje a rozhoduje. Tím:

Subagenti zůstávají jednodušší.
Single source of truth — Mara konsoliduje pohled napříč týmem.
Méně halucinací — jeden bod kde se klasifikace dělá.

Kai ani Eli nemají žádný pleaseReportIssue API. Mara nikdy nedeleguje rozhodnutí “je to platform bug” na subagenty.

Klíčové omezení Phase 1

target = PLATFORM pouze — target = PROJECT je vyhrazeno pro Phase 3 (#83). Phase 3 (#91) toto omezení ruší.
kind enum: BUG | FEATURE pouze — INCIDENT přijde s environments feature (#84).
severity = CRITICAL nastavuje výhradně admin při triage — Mara ani USER nikdy.
Žádné Studio UI pro issues v Phase 1 — pouze Mara tools + admin REST API. Phase 3 (#91) přidává Studio UI.
reporter_agent whitelist: MARA pouze — Phase 2 (#87 / UC-09008) rozšiřuje na MARA | USER pro PLATFORM target.

Out of scope (Phase 1)

Co	Proč	Odkaz
Studio UI — admin triage + user view pro issues	UI implementace je separátní fáze	#82 Phase 2
`target=PROJECT` — user-app TODO/bug list	Závisí na per-app issue ownership modelu	#83 Phase 3
`INCIDENT` kind + `environment_id` FK	Vázáno na environments feature	#84
GitLab issue escalation s PII strip	`context_jsonb` může obsahovat user data — exfiltrace vyžaduje explicit strip step	future
SSE notifikace reporterovi při RESOLVED	”retry?” push do Mara session	future
Pattern detection cron + auto-severity bump	Analytics feature nad issues tabulkou	future
User-facing “Nahlásit problém” tlačítko	`USER` jako `reporter_agent`	#87 Phase 2 — implementováno UC-09008
Kai/Eli vlastní reporting	Záměrně nikdy — Mara konsoliduje	N/A

DB schema

Phase 1: Zavedeno Liquibase migrací 0019-create-issues-tables.xml (nový soubor, immutable po deploymentu na prod — viz CLAUDE.md pravidla pro production phase). Viz UC-09001 — DB Migration pro kompletní changeset XML.

Phase 3 (#91): Nová migrace 0020-add-project-fk-to-issues.xml doplňuje FK constraint issues.project_id → projects.id ON DELETE CASCADE (omylem vynechán v 0019). Viz UC-09005 — DB Migration.

issues (id, target, project_id, tenant_slug, reporter_user_id, reporter_agent,
        session_id, title, description, kind, severity, status, context_jsonb,
        resolved_by_user_id, resolution_note, parent_issue_id,
        reported_at, triaged_at, resolved_at)

issue_comments (id, issue_id, author_user_id, author_agent, body, created_at)

REST API přehled

Method	Path	Auth	UC
POST	/api/issues	Agent JWT (Mara) / User JWT	UC-09001 (Mara, PLATFORM), UC-09008 (User, PLATFORM), UC-09005 (Phase 3, PROJECT)
GET	/api/issues	Agent JWT (Mara) / User JWT / Admin	UC-09002, UC-09006
GET	/api/issues/{id}	Agent JWT (Mara) / User JWT / Admin	UC-09002
POST	/api/issues/{id}/comments	Agent JWT (Mara)	UC-09003
PATCH	/api/issues/{id}	Admin JWT (platform_admin)	UC-09004

Was this page helpful?

Thanks for the feedback.