Gastown bug reporting — issue template, UI link, and Mayor gt_report_bug tool

[jrf0110]

Parent

Part of #204 (Phase 4: Hardening)

Problem

There's no structured way for users (or the Mayor) to report Gastown bugs. No issue template exists on the Kilo-Org/cloud repo, no link in the UI points users to file issues, and the Mayor has no ability to report problems it encounters.

Solution

Three parts: issue template, UI link, and Mayor bug reporting tool.

1. GitHub issue template for Gastown bugs

Create .github/ISSUE_TEMPLATE/gastown-bug.yml on the Kilo-Org/cloud repo with structured fields:

name: "Gastown Bug Report"
description: "Report a bug with Gastown by Kilo"
labels: ["gastown", "bug"]
body:
  - type: textarea
    id: description
    attributes:
      label: What happened?
      description: Describe the bug. What did you expect to happen vs. what actually happened?
    validations:
      required: true
  - type: dropdown
    id: area
    attributes:
      label: Area
      options:
        - Mayor / Chat
        - Terminal UI
        - Bead Board / Dashboard
        - Convoys
        - Merge Queue / Refinery
        - Agent Dispatch / Scheduling
        - Container / Git
        - Other
    validations:
      required: true
  - type: input
    id: town-id
    attributes:
      label: Town ID (if known)
      description: Found in the URL or town settings
    validations:
      required: false
  - type: textarea
    id: reproduction
    attributes:
      label: Steps to reproduce
      description: How can we reproduce this?
    validations:
      required: false
  - type: textarea
    id: logs
    attributes:
      label: Relevant logs or screenshots
      description: Paste any error messages, activity log entries, or screenshots
    validations:
      required: false

2. Bug report link in the Gastown UI

Add a "Report a Bug" link accessible from the Gastown dashboard. Options for placement:

• In the terminal bar's status tab (near the alarm status info)
• In the town settings page
• In a help menu / ? button in the header

The link opens the prefilled issue template URL:

https://github.com/Kilo-Org/cloud/issues/new?template=gastown-bug.yml&labels=gastown,bug

For users who can't access the GitHub repo (private repo), the link should go to a public feedback form or a support channel instead.

3. Mayor bug reporting tool — gt_report_bug

A new Mayor tool that files a GitHub issue on the Kilo-Org/cloud repo when the Mayor encounters or is told about a bug. The Mayor already has access to GH_TOKEN in the container for GitHub CLI operations.

Flow:

1. User tells the Mayor about a bug, or the Mayor encounters an error during tool calls
2. Mayor searches existing issues first to avoid duplicates: gh issue list --repo Kilo-Org/cloud --label gastown,bug --search "<keywords>"
3. If no existing issue matches, Mayor creates one: gh issue create --repo Kilo-Org/cloud --template gastown-bug.yml --title "..." --body "..."
4. Mayor includes structured context automatically:
   • Town ID, rig ID
   • Agent role and ID
   • Recent bead events / error context
   • What the user reported
5. Mayor responds with the issue URL so the user can track it

Prompt guidance:

## Bug Reporting

If a user reports a bug or you encounter a repeating error, you can file a bug report 
using gt_report_bug. Before filing:
1. Search existing issues to avoid duplicates
2. Include the town ID, what went wrong, and any error context
3. Share the issue URL with the user

Only file bugs for genuine system problems — not for user errors or expected behavior.
Don't file bugs for issues you can resolve yourself (e.g., re-slinging a failed bead).

When the Mayor can't be reached: The UI bug report link (part 2) is the fallback. If the container is down, the Mayor is unresponsive, or the terminal is frozen, users still have a direct path to file an issue.

Acceptance Criteria

• .github/ISSUE_TEMPLATE/gastown-bug.yml created on Kilo-Org/cloud repo
• "Report a Bug" link in the Gastown dashboard UI pointing to the template
• gt_report_bug Mayor tool that searches existing issues and creates new ones
• Mayor includes structured context (town ID, rig, recent errors) in bug reports
• Mayor searches for duplicates before filing
• Bug reports labeled gastown + bug automatically
• Fallback UI link works when the Mayor/container is unavailable

Notes

• The GH_TOKEN in the container is already used for PR operations — it should have issues: write scope. Verify this before implementing.
• Consider whether bug reports from the Mayor should use a bot-specific label (e.g., reported-by-mayor) so we can distinguish user-filed from Mayor-filed issues
• The Mayor should NOT file bugs about itself being unable to start — that's a chicken-and-egg problem. The UI link covers that case.
• If the Kilo-Org/cloud repo is private, the issue template URL won't work for external users. We'd need either a public issues repo or an alternative feedback mechanism (email, form, Discord).