Bug Reporter

Capture and report bugs with automatic context gathering, local logging, GitHub issue creation, and pattern sharing.

When to Use

• User reports a bug or issue with /popkit:bug
• Agent encounters repeated errors or gets stuck
• Need to document an issue for later investigation
• Want to share a bug pattern with the collective

Input

User provides:

• Bug description
• Optional flags: --issue, --share, --verbose, --no-context
• Or subcommands: list, view <id>, clear

Process

1. Parse Request

Determine the action:

• Default: Report new bug
• list: List logged bugs
• view: View specific bug
• clear: Clear logs

2. Capture Context (for new bug)

Gather automatic context using hooks/utils/bug_context.py:

from bug_context import BugContextCapture, format_bug_report, format_github_issue

capture = BugContextCapture()
ctx = capture.capture(
    description=user_description,
    recent_tools=recent_tool_calls,
    agent_state=current_agent_state
)

Context includes:

• Recent tool calls (last 10)
• Files touched
• Error messages detected
• Agent progress and current task
• Project type (language, framework)
• Git status (branch, uncommitted changes)
• Stuck patterns (same file edited 3+ times, build failures)

3. Generate Report

Format the bug report:

Bug Report
==========
ID: bug-2024-12-04-abc123
Time: 2024-12-04T10:30:00Z

Description: Agent got stuck on OAuth flow

Context:
  Language: TypeScript
  Framework: Next.js
  Branch: feature/oauth
  Uncommitted: 3 files

Recent Actions:
  1. Edit src/auth/oauth.ts
  2. Bash: npm run build (failed)
  3. Edit src/auth/oauth.ts (same file, 2nd time)

Errors Detected:
  [TypeError] Cannot read property 'token' of undefined

Stuck Patterns:
  - Same file edited 3 times: oauth.ts
  - Build command failed

Suggested Actions:
  - Consider stepping back and reviewing the approach
  - Check for null/undefined values

4. Output Actions

Based on flags:

Default - Log locally:

file_path = capture.save(ctx)
print(f"Logged to: {file_path}")

--issue - Create GitHub issue with validated labels (Issue #96):

from popkit_shared.utils.github_validator import validate_labels
from popkit_shared.utils.github_cache import GitHubCache

issue_body = format_github_issue(ctx)

# Validate default bug labels
default_labels = ["bug", "needs-triage"]
cache = GitHubCache()
valid, invalid, suggestions = validate_labels(default_labels, cache)

# Auto-fix or fallback
if invalid:
    fixed_labels = valid.copy()
    for s in suggestions:
        if s['suggestions']:
            fixed_labels.append(s['suggestions'][0])
    labels_to_use = fixed_labels if fixed_labels else []
else:
    labels_to_use = valid

# Create issue (don't block on invalid labels)
if labels_to_use:
    gh issue create --title "Bug: ..." --body issue_body --label {','.join(labels_to_use)}
else:
    gh issue create --title "Bug: ..." --body issue_body

--share - Share to collective (Pro/Team):

# Anonymize pattern
# Upload to collective learning database

5. Confirm to User

Show:

• Bug ID
• Actions taken (logged, issue created, shared)
• Link to issue if created

Subcommand Handlers

list

bugs = capture.list_bugs(limit=10)
# Format as table with ID, date, description

view

ctx = capture.get_bug(bug_id)
if ctx:
    print(format_bug_report(ctx, verbose=True))

clear

cleared = capture.clear_bugs(before=date, bug_id=id)
print(f"Cleared {cleared} bug reports")

Anonymization for Sharing

When --share is used, anonymize before uploading:

Original	Anonymized
<project>/src/auth/oauth.ts	auth module
handleTokenRefresh()	token refresh handler
API keys, secrets	[REDACTED]
Variable names	Generic terms

def anonymize_pattern(ctx: BugContext) -> Dict:
    return {
        "trigger": abstract_error(ctx.errors[0] if ctx.errors else None),
        "context": {
            "language": ctx.project.language,
            "framework": ctx.project.framework,
            "error_type": ctx.errors[0].error_type if ctx.errors else None
        },
        "stuck_patterns": ctx.stuck_patterns,
        "suggested_actions": ctx.suggested_actions
    }

Example Flows

Report Bug (Default)

User: /popkit:bug "Agent can't find the right file"

[Capturing context...]
- Recent tools: 8 calls
- Files touched: 4
- Errors: 1 (ENOENT)
- Git: feature/search branch

Bug Report
==========
ID: bug-2024-12-04-def456
...

Logged to: .claude/bugs/bug-2024-12-04-def456.json

Create GitHub Issue

User: /popkit:bug "Tests failing after refactor" --issue

[Capturing context...]
[Creating GitHub issue...]

Bug Report Created
==================
ID: bug-2024-12-04-ghi789
GitHub Issue: #123
URL: https://github.com/user/repo/issues/123

Logged locally and issue created.

Share Pattern

User: /popkit:bug "OAuth token refresh failing" --share

[Capturing context...]
[Anonymizing pattern...]
[Uploading to collective...]

Bug Report
==========
ID: bug-2024-12-04-jkl012
Pattern shared: Yes (anonymized)
Collective ID: pattern-abc123

Thank you for contributing to the collective learning database!

Integration Points

Component	Purpose
hooks/utils/bug_context.py	Context capture and formatting
.claude/bugs/	Local bug storage
power-mode/insight_embedder.py	Pattern sharing
gh issue create	GitHub issue creation

Output Style

Use a clear, structured format:

• Show bug ID prominently
• List context in organized sections
• Highlight errors and stuck patterns
• Provide actionable suggestions
• Confirm what actions were taken