Skip to main content

​
/report — Comprehensive Bug Report

Investigate bugs end-to-end: collect symptoms, run /trace for root cause analysis, capture browser evidence, pull observability data, and auto-create a GitHub issue with all findings.

​
When to Use

  • A bug needs thorough, documented investigation before fixing
  • A GitHub issue is needed with reproduction steps, root cause, and evidence
  • Multiple evidence sources should be combined into one report
  • During QA loop: test failures need investigation

​
Flow

​
Phase 1: Collect Symptoms

Accept user input:
  • Bug description — what’s going wrong
  • URL (optional) — page or endpoint where the bug manifests
  • Error messages — any error text, stack traces, or console output
  • Expected vs actual behavior

​
Phase 2: Run /trace (Code-Level Investigation)

Always run. Dispatches /trace for source analysis, reproduction, root cause hypothesis, and causal chain construction.

​
Phase 3: Browser Investigation (Opportunistic)

If a URL or dev server is available, capture:
  • Screenshots of affected pages
  • Console errors and warnings
  • Failed network requests
Uses agent-browser when available. Degrades gracefully if not installed.

​
Phase 4: Observability Data (Project-Dependent)

Detect and query project-configured observability tools:
ToolDetection
SentrySENTRY_DSN env var, @sentry/* in package.json
PostHogPOSTHOG_KEY env var
DataDogDD_API_KEY env var
Generic logs*.log files, logs/ directory

​
Phase 5: Compile Report

Merge all evidence into a structured GitHub issue body with sections for summary, reproduction steps, root cause analysis, evidence (screenshots, console, network, observability), environment, and suggested fix.

​
Phase 6: Create GitHub Issue

gh issue create --title '<title>' --body '<report>' --label bug
Falls back to printing the report as markdown if gh is not authenticated.

​
Degradation Rules

Each phase is independent — failure in one never blocks the others:
ConditionBehavior
No browser / no URLSkip Phase 3, add note
No observability toolsSkip Phase 4, add note
No gh authPrint report to stdout
/trace failsContinue with available evidence

​
Task Lifecycle Integration

When invoked during the QA loop, /report links findings to wish acceptance criteria and logs them to task comments:
EventCommand
Investigation startgenie task comment #<seq> "Report: investigating [bug summary]"
QA criterion failuregenie task comment #<seq> "QA FAIL: criterion '<text>' — [reason]"
Issue createdgenie task comment #<seq> "Filed: gh#<number> — [title]"
The auto-invocation chain for QA failures: QA failure → /report → /trace → /fix → retest.

​
Rules

  • Always run /trace first — it’s the backbone of every report
  • One question at a time when collecting symptoms
  • Never modify source code — investigation only
  • The report must be self-contained
  • If identical to an existing open issue, link instead of duplicating