Internal Documentation internal
← Back to TalkIDE
TalkIDE internal documentation

What this context does

A persistent channel for agents (primarily Mara) to report problems to the TalkIDE platform team — and, in Phase 3, for users to report bugs in their own apps. It exists because Mara used to hallucinate “I logged this for the TalkIDE team” without anything actually being persisted (a real Stopa B deploy incident, 2026-05-13: a registry-write token failure was never recorded and the user had to diagnose it themselves).

The data model is deliberately universal — target = PLATFORM | PROJECT — so the same issues table serves both platform issue reporting and future user-app issue tracking.

Scope boundary

  • Owns: issues and issue_comments tables, the Issue state machine, the Mara tools report_issue / search_issues / comment_issue, the admin triage endpoint, and the injection of open project issues into CLAUDE.md.
  • Does not own: GitLab escalation (future), SSE “retry?” notifications back to a Mara session (future), pattern-detection / auto-severity cron (future).

Main entities

ISSUE — id, target (PLATFORM/PROJECT), projectId, tenantSlug, reporterUserId, reporterAgent (MARA/USER), sessionId, title, description, kind (BUG/FEATURE; INCIDENT reserved for the environments feature), severity (CRITICAL set by admin only), status, contextJsonb (server-enriched: K8s events, pod logs, conversation snippet, project state), resolvedByUserId, resolutionNote, parentIssueId (duplicate-of link), and the reportedAt/triagedAt/resolvedAt timestamps.

ISSUE_COMMENT — id, issueId, authorUserId, authorAgent, body, createdAt.

Use cases

UCPhaseWhat it does
UC-090011Report Platform Issue — Mara tool report_issue, server-side context enrichment, rate limit 5/h/session, 10-min dedup window
UC-090021Search Issues — search_issues tool, LIKE filter, scoped by reporterUserId for non-admins
UC-090031Comment Issue — Mara adds context on recurrence
UC-090041Admin Triage Issue — status transitions, CRITICAL override, duplicate-of links
UC-090053Report Project Issue — dual reporter (USER via Workspace modal / MARA via tool)
UC-090063View Project Issues — Workspace tab, Studio widget, /studio/issues page
UC-090073Mara Injects Open Issues — # Open TODO issues section in CLAUDE.md

Reporting authority

Dependencies on other contexts

  • UC-04 Conversation — issues are reported as side effects of a Mara turn; sessionId links an issue back to its conversation.
  • UC-08 Mara Platform — Mara tools run inside the agent runtime fronted by the gateway.
  • UC-03 Project Management — Phase 3 target=PROJECT issues carry a projectId FK with ON DELETE CASCADE.

Cross-cutting

  • Server-side context enrichment — the BE, not Mara, attaches K8s events, pod logs and project state to contextJsonb. Mara cannot fabricate diagnostics.
  • Immutable Liquibase — Phase 1 schema is 0019-create-issues-tables.xml; Phase 3 adds the missing project FK in 0020-add-project-fk-to-issues.xml (production phase — no in-place edits).
Was this page helpful?

Thanks for the feedback.