# in-app-bug-reports (Agent Skill)

> A report-a-bug button whose reports become GitHub issues: saved in the app first and delivered through an outbox, status mirrored back, team replies shown on request, private attachments, and an assistant that drafts.

Page: https://timerise.ai/skills/in-app-bug-reports

Agent Skill `in-app-bug-reports`: https://github.com/timerise-ai/in-app-bug-reports. Category: AI & integrations. Runs on Next.js; backend: Postgres/Supabase with row-level security behind a `BugReportsHost` seam; GitHub behind an `IssueTracker` seam.

Latest release: v0.1.4 (2026-10-07).

Install: npx skills add timerise-ai/in-app-bug-reports. Timerise builds it on a brief; the price comes from the brief.

Users find bugs; engineers fix them in GitHub. Between the two sits an e-mail, a support ticket or a screenshot in a chat, and the report loses detail at every hop. The user never hears whether it was fixed.

A "report a bug" button that opens a GitHub issue looks easy. It goes wrong in quiet ways. A retry opens the same issue twice. An outage at GitHub loses the report. An internal comment from the team shows up in front of a customer. A screenshot sits at a public URL. The app says "open" long after the bug was closed.

This skill gives a coding agent the bridge the way we build it: the report is saved in the app first and reaches GitHub through an outbox, so an outage delays it and loses nothing. GitHub's own state becomes the report's status. The team answers with `/reply` comments, the only ones a user sees. Attachments stay behind sign-in, operators see every tenant in one view, and an in-app assistant can draft a report that the user sends.

Build an in-app bug report module in a Next.js App Router app that files every report as a GitHub issue: members of any tenant report with a title, markdown and attachments, the issue's state comes back as the report's status, the team answers with /reply comments, operators see every tenant, and an AI assistant tool drafts a report that the member sends. Use when: (1) adding a "report a bug" or "send feedback" button whose reports land in GitHub Issues, (2) mirroring issue status and replies back into the app, (3) letting an assistant draft a bug report without letting it send one, (4) an existing bridge loses reports, opens duplicate issues, leaks internal comments or never updates status, (5) the user mentions: bug report, report a bug, feedback button, GitHub Issues integration, GitHub App, installation token, X-Hub-Signature-256, issue webhook, issue_comment, state_reason, not_planned, /reply, outbox, Vercel Cron 404, "Domain not configured" on a webhook, signed upload URL, createSignedUploadUrl, private attachments, draft tool, needs approval. Carries an outbox with marker de-duplication, the webhook rules that keep the team's conversation private, login-gated attachments that never become public URLs, cron and webhook routes that a multi-tenant proxy serves without a tenant, and 50 tests. Next.js App Router with Postgres and Supabase RLS; the host seam is one BugReportsHost object and a client UI module, and the tracker sits behind IssueTracker. Not error monitoring, not a help center and not a support inbox.

This skill was written by the engineer who has shipped this module. The earlier implementation it was audited against was the bug report bridge of a multi-tenant console on Next.js 16, Vercel and Supabase, with an assistant on the AI SDK. The templates hold the properties such a bridge has to hold: one issue per report however often a job retries, no team comment shown to a tenant without an explicit `/reply`, no attachment reachable without a sign-in, workers and the webhook reachable on a multi-tenant proxy, and an assistant that drafts but cannot send. The suites in [`references/testing.md`](references/testing.md) state each one; [`references/provenance.md`](references/provenance.md) has the record.

What it builds:
- Reports with markdown and attachments saved under tenant policies first and delivered through an outbox with marker de-duplication
- The issue's state mirrored back as the report's status
- /reply comments as the only team replies a member sees
- Attachments that stay private behind sign-in
- An operator view across tenants with bridge health
- An assistant tool that drafts a report the member sends

When to use:
- A product wants its users to report bugs from inside the app, into the repository the team uses.
- The team wants to answer and close reports in GitHub and have the app reflect it.
- An assistant in the app should help write a report without being able to send one.

When not to use:
- **Crash and exception capture**: an error monitoring service. This module files what a person writes.
- **Help articles and search**: the `help-center-markdown` skill; link its pages to this form.
- **Customer support conversations**: a support inbox. Reports here go to engineers, not to agents.
- **Assistants in Slack**: the `slack-ai-bot` skill, which carries its own approval round trip.
- **Resolving a report once it arrives**: the `resolve-bug-report` skill, from evidence to the `/reply`.

Non-negotiables:
- Never let the app write a status. GitHub's state is the only writer, through the webhook and the reconcile pass. Members have no UPDATE policy and no privilege, and nobody has a close button; the RLS checks in `references/data-model.md` show an update refused.
- Never show a tracker comment to a tenant unless it opts in. Visible only with `/reply` on the first line from an owner, member or collaborator of the repository. `parseReplyCommand` and `planDelivery` carry the rule and their suites hold it.
- Never call the tracker inside the request that saves the report. Save, enqueue, return; the outbox sends and de-duplicates by marker on every retry, so a report is never refused or doubled by GitHub's state.
- Never publish an attachment. Private bucket, a 404 for everyone but an operator or the report's tenant, a 60-second signed URL, no SVG or HTML. The policies confine reservations to the tenant's folder.
- Never let the assistant send. The draft tool reads nothing and writes nothing; the member's click on the card runs the same Server Action as the form.

Not this:
- Capturing crashes and exceptions automatically: An error monitoring service. This module files what a person writes
- A help center with articles and search: The `help-center-markdown` skill; link its pages to the report form
- Customer support conversations and SLAs: A support inbox. Reports here go to engineers, not to agents
- An assistant in Slack with approvals: The `slack-ai-bot` skill
- Mirroring every issue of a repository: A GitHub sync tool. This module bridges the issues it created, by label and marker
- Resolving one report: evidence, fix, proof and the `/reply`: The `resolve-bug-report` skill

Requirements:
- **Next.js App Router** with Server Actions and `after()`, on a Node runtime.
- **Postgres with Supabase** for the reference store: RLS, Storage and the two clients. Another stack ports the store on the rules in `references/adaptation.md`.
- A **GitHub App** you control, installed on one private repository, and a host the proxy serves without resolving a tenant for the operators and the webhook.
- A scheduler that calls a route every five minutes with a bearer: Vercel Cron, or any other.
- `zod`, `@supabase/supabase-js`, `@supabase/ssr`, `server-only`, `vitest` for the suites, and `ai` 7 for the assistant tool, installed with the app's package manager.

What to tell your agent:
- Add a 'report a bug' button to this app. People should be able to write what went wrong, attach screenshots, and see the team's replies and whether it was fixed. The team works in GitHub Issues.
- Our in-app assistant should be able to help a user write up a bug report, but the user has to be the one who sends it.
- Bug reports from the app reach GitHub, but closing the issue never updates the report in the app. Find out why.

Agent eval results (newest per agent and prompt):
- Codex CLI (gpt-6.1-sol) on v0.1.4, 2026-10-07: pass (Postgres)
- Gemini CLI (gemini-3.8-flash) on v0.1.4, 2026-10-07: pass (Postgres)
- Claude Code (claude-opus-5-5) on v0.1.4, 2026-10-07: pass (Postgres)

Recent releases:
- v0.1.4 (2026-10-07): Fix release, from scoring the prompt-1 agent eval runs against 0.1.3.
- v0.1.3 (2026-10-07): Fix release, from scoring the prompt-1 agent eval runs against 0.1.2.
- v0.1.2 (2026-10-07): Fix release, from scoring the prompt-1 agent eval runs against 0.1.1.
