mikeparcewski/issue-reporting

Issue Reporting

Detects and reports bugs, UX friction, and unmet outcomes as structured GitHub issues. The manual filing command runs research, validates quality, and enriches the issue body before filing.

How It Works

Automatic Detection (Hooks)

Three hooks monitor your session:

| Hook | Watches For | Action | |------|------------|--------| | PostToolUseFailure | Same tool failing 3+ times | Queues issue for session end | | PostToolUse(TaskUpdate) | Task completed with mismatch signals | Logs mismatch for review | | Stop (async) | Session end | Files queued issues via gh |

Auto-filed issues include acceptance criteria, failure details, and session context.

Manual Filing

/wicked-garden:report-issue bug          # File a bug report
/wicked-garden:report-issue ux-friction  # Report UX friction
/wicked-garden:report-issue unmet-outcome # Log an unmet outcome
/wicked-garden:report-issue --list-unfiled # View/file unfiled issues

Manual filing runs a full research and quality pipeline before opening the issue:

1. Collect fields — interactive prompts by issue type
2. Research — duplicate detection, codebase search, memory recall
3. SMART validation — acceptance criteria checked for specificity and measurability
4. Quality gate — advisory checklist (title length, AC count, verb prefix, etc.)
5. Confirm and file — preview shown before any gh call

Issue Types

| Type | Label | When To Use | |------|-------|-------------| | Bug Report | bug | Tool failures, crashes, incorrect behavior | | UX Friction | ux | Confusing workflows, missing feedback, rough edges | | Unmet Outcome | gap | Session goal not achieved, partial results |

Each issue type has a structured template requiring:

• Steps to reproduce or context
• Expected vs actual behavior
• Acceptance criteria for the fix (SMART-validated)
• Desired outcome

Research Pipeline (Manual Filing Only)

Before composing the issue body, the command runs three research steps:

Duplicate Detection

Searches open issues by title keywords:

gh issue list --repo {repo} --search "{keywords}" --state open --json number,title,state --limit 10

Results are appended as a Duplicate Check section. Requires gh CLI.

Codebase Research

Greps the repository for files related to the issue keywords. Up to 5 relevant files are listed in a Related Code section.

Memory Recall

Queries the wicked-brain memory store for prior context about the issue area:

Skill(skill="wicked-brain:memory", args="recall {keywords}")

Relevant memories are appended as a Prior Context section.

All three steps are additive — they never block filing.

SMART Criteria Validation

Every acceptance criterion is validated before the issue body is finalized:

| Criterion | Requirement | Bad Example | Good Example | |-----------|-------------|-------------|--------------| | Specific | References a concrete behavior, file, or artifact | "should work better" | "Bash hook returns {\"ok\": true}" | | Measurable | Verifiable assertion that is clearly true or false | "no errors occur" | "passes /wg-check" |

ACs that fail are auto-improved in non-interactive mode, or surfaced with a suggested rewrite in interactive mode.

Quality Gate

An advisory checklist runs before the issue preview is shown. All items are warnings only — they never block filing:

| Check | Criteria | |-------|----------| | Title length | Under 80 characters | | Title descriptiveness | Not a single word or generic phrase | | Steps to reproduce | For bugs: at least 2 numbered steps | | Acceptance criteria count | At least 2 ACs | | AC verb prefix | Each AC starts with an action verb | | AC independence | Each AC is independently verifiable | | Duplicate check | Duplicate search completed |

Configuration

| Setting | Default | Override | |---------|---------|---------| | Failure threshold | 3 | WICKED_ISSUE_THRESHOLD env var | | Max issues per session | 3 | Hardcoded in session_outcome_checker.py | | Stale session cleanup | 48h | Hardcoded in auto_issue_reporter.py |

Prerequisites

• gh CLI installed and authenticated (gh auth login)
• Current directory is a GitHub repository

Without gh, the manual filing fallback uses a three-step sequence (see below).

Fallback When gh Unavailable

When gh CLI is not installed or no repo is detected, manual filing follows this order:

1. Print to screen: Full issue displayed as formatted markdown (title, body, labels) — immediately visible for copy-paste
2. Generate GitHub URL: Pre-filled issues/new URL with urllib.parse.quote()-encoded title, body, and labels — open in browser to file directly
3. Ask to save locally: User chooses whether to cache the issue for later filing

https://github.com/{owner}/{repo}/issues/new?title={encoded}&body={encoded}&labels={encoded}

If user agrees to save: issue is queued in {storage_root}/unfiled-issues/ for later filing via --list-unfiled.

Note: Hook auto-filing paths (PostToolUseFailure, Stop hook) bypass this flow and silently cache to the unfiled queue without prompting.

References

• Issue Templates — Full body templates for all three issue types, including Research and Duplicate Check sections