Bug Report Generator

Generate structured, PII-redacted bug reports that users can copy-paste into the ClawedBack GitHub issue tracker.

When to Trigger

Offer to generate a report when:

• A Python traceback occurs during message processing
• A server error (HTTP 500) is detected
• A skill fails to execute
• Voice transcription fails repeatedly
• The server crashes and needs restart
• Any unexpected error the user reports via chat

Ask the user: "Would you like me to generate a bug report you can submit to the developer? No personal information will be included."

Only proceed if they say yes.

Step 1: Gather Context

Collect this information (all will be redacted before output):

# Git version
cd $PROJECT_ROOT && git rev-parse --short HEAD 2>/dev/null || echo "unknown"

# OS info
uname -srm

# Python version
python3 --version

# Install mode and config
cat $PROJECT_ROOT/data/clawedback.json 2>/dev/null

# Recent server logs (last 30 lines)
tail -30 $PROJECT_ROOT/data/logs/server.log 2>/dev/null

# Recent queue activity
cd $PROJECT_ROOT/.claude/skills/oc-poll/scripts && python3 queue_manager.py history 5 2>/dev/null

Also note:

• What the user was doing when the error occurred (from conversation context)
• The exact error message or traceback
• Any relevant details from the current session

Step 2: Redact All PII

Before including ANY gathered text in the report, apply these redactions:

Mandatory Redactions

What to find	Replace with
IP addresses (\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})	[REDACTED_IP]
Username (read from data/clawedback.json username field, also check $USER, whoami)	[REDACTED_USER]
Home directory paths (/home/<username>, /root)	/home/[REDACTED_USER]
Project root absolute path	$PROJECT_ROOT
Auth token (from data/.auth_token)	[REDACTED_TOKEN]
Any value that matches the auth token in logs/output	[REDACTED_TOKEN]
Hostname/FQDN (from hostname command)	[REDACTED_HOST]
MAC addresses ([0-9a-f]{2}(:[0-9a-f]{2}){5})	[REDACTED_MAC]
Email addresses	[REDACTED_EMAIL]
host_url value from clawedback.json	[REDACTED_URL]

Redaction Process

1. Read the username from data/clawedback.json (username field)
2. Read the auth token from data/.auth_token
3. Read the hostname via hostname
4. Read the host_url from data/clawedback.json
5. For every string you include in the report, do a find-and-replace pass for ALL of the above
6. Then do a regex pass for IP addresses, MAC addresses, and email patterns
7. Double-check: scan the final report one more time for any remaining PII

What to KEEP (useful for debugging)

• Port numbers (8080, 443, etc.)
• Python version
• OS name and version
• Error types and messages (after path redaction)
• File names (without full paths) — e.g., main.py not /home/user/clawedback/.claude/skills/oc-poll/scripts/main.py
• Timestamps
• HTTP status codes
• Package versions

Step 3: Format the Report

Use this exact template:

## Bug Report -- ClawedBack

**Version:** [git short hash]
**Date:** [YYYY-MM-DD HH:MM UTC]
**Install Mode:** [a/b/c]
**OS:** [uname output, redacted]
**Python:** [version]

### What Happened

[1-3 sentence description of what went wrong, written from the user's perspective]

### Error Details

\`\`\`
[Redacted error message or traceback]
\`\`\`

### Steps to Reproduce

1. [What the user was doing before the error]
2. [The action that triggered the error]
3. [What happened instead of the expected behavior]

### Expected Behavior

[What should have happened]

### Environment

| Setting | Value |
|---------|-------|
| Install Mode | [a/b/c] |
| Voice | [enabled/disabled] |
| SSL | [enabled/disabled] |
| Whisper Model | [model name or N/A] |

### Recent Server Logs (redacted)

\`\`\`
[Last 20 lines of server.log, fully redacted]
\`\`\`

### Additional Context

[Any other relevant details — what skills were active, what was tried to fix it, etc.]

---
*Generated by ClawedBack Bug Reporter. All personally identifiable information has been removed.*

Step 4: Save and Share

1. Write the report to a temporary file:

# Generate filename
REPORT_FILE="$PROJECT_ROOT/data/reports/report_$(date +%Y%m%d_%H%M%S).md"

2. Write the formatted report content to that file.

3. Store it via file_manager:

cd $PROJECT_ROOT/.claude/skills/oc-poll/scripts && python3 file_manager.py store "$REPORT_FILE" --name "bug_report_$(date +%Y%m%d).md" --type generated

4. Create a 24-hour download link:

cd $PROJECT_ROOT/.claude/skills/oc-poll/scripts && python3 file_manager.py share <file_id> --name "bug_report.md" --duration 86400

5. Send the link to the user via the queue:

Here's your bug report (link expires in 24 hours):

[download link]

To submit it:
1. Open the link and copy the contents
2. Go to https://github.com/reedmayhew/clawed-back/issues/new
3. Paste the report as the issue body
4. Add a short title describing the bug
5. Submit

No personal information is included in the report.

Step 5: Clean Up

• Delete the temporary file after storing it via file_manager
• Do NOT store the raw (un-redacted) data anywhere

Important Rules

• NEVER include un-redacted data in the report — redact first, write second
• NEVER send the report automatically — always ask the user first
• NEVER include conversation content beyond what's needed to describe the bug
• NEVER include file contents the user uploaded (only mention that files were involved)
• Keep it concise — developers need signal, not noise
• If in doubt, redact it — better to over-redact than to leak PII