Filing User Bug Reports

Filing User Bug Reports

Description

Process conversations or chat logs to identify reported bugs, search for existing GitHub issues, update existing issues when new undocumented details are discovered, and create new issues for untracked problems.

When to Use

• After team discussions in chat channels (Telegram, Slack, Discord, etc.)
• When reviewing user feedback or support conversations
• During triage sessions to ensure all reported bugs are tracked
• When consolidating bug reports from multiple sources

Process

1. Identify Reported Bugs

Read through the conversation and identify:

• Explicit bug reports: "There is a bug with...", "I'm experiencing an issue where..."
• Problem statements: "This isn't working...", "When I do X, Y happens instead of Z"
• Confirmation from multiple users: When multiple people report the same issue
• Workarounds mentioned: Often indicates an underlying bug

Look for:

• Specific reproduction steps
• Expected vs actual behavior
• Reproducibility (always, sometimes, specific conditions)
• Confirmation or denial by other users
• Workarounds or temporary fixes

2. Search for Existing Issues

For each identified bug, search GitHub using the gh CLI tool:

# Search by keywords from the bug description
gh issue list --repo <org>/<repo> --search "keyword1 keyword2" --limit 10 --json number,title,state,url

# Search by feature area
gh issue list --repo <org>/<repo> --search "feature area" --limit 10 --json number,title,state,url

# List issues with specific labels
gh issue list --repo <org>/<repo> --state open --label "bug" --limit 20 --json number,title,state,url

Search Strategy:

• Use multiple search queries with different keyword combinations
• Search for related features, not just exact matches
• Check both open and closed issues
• Review issue titles and bodies to confirm relevance

3. Categorize Findings

For each bug, determine:

• ✅ Already Tracked: Existing open issue found and no meaningful new information was discovered
• 📝 Needs Existing Issue Update: Existing issue found, but the conversation includes new undocumented details worth adding
• ⚠️ Needs New Issue: No existing issue found
• 🔄 May Be Duplicate: Similar issue exists but needs verification
• ❓ Needs More Info: Insufficient details to create or update an issue

4. Update Existing Issues or Create New Issues

For bugs that are already tracked but include new, undocumented details, update the existing GitHub issue with the newly gathered information. Add only net-new technical context such as clearer reproduction steps, environment details, frequency, workarounds, scope, or confirmations from additional users.

Example update command:

gh issue comment <issue-number> --repo <org>/<repo> --body "New information gathered from follow-up reports:\n\n- Updated reproduction steps: ...\n- Environment details: ...\n- Frequency: ...\n- Additional impact or workaround: ..."

If the existing issue body should be revised instead of just commented on, update it directly with gh issue edit so the canonical issue description stays current.

For bugs that need new tracking, create a GitHub issue using:

gh issue create --repo <org>/<repo> \
  --title "Clear, descriptive title" \
  --body "$(cat <<'EOF'
## Description
Clear description of the bug

## Steps to Reproduce
1. Step one
2. Step two
3. Step three

## Expected Behavior
What should happen

## Actual Behavior
What actually happens

## Environment
- Platform: iOS/Android/Web
- Version: X.Y.Z
- Source: Team chat discussion (Date)

## Additional Context
- Reproducibility: Always/Sometimes/Once
- Affected users: Multiple/Single
- Workaround: Yes/No
EOF
)" \
  --label "bug"

Issue Writing Guidelines:

• No Personal Information: Never include user names, email addresses, or identifying information
• Be Specific: Include concrete details, not vague descriptions
• Include Context: Platform, version, feature area
• Note Reproducibility: Is it consistent or intermittent?
• Link Related Issues: Reference existing issues if related
• Use Appropriate Labels: bug, feature-request, enhancement, etc.

5. Summary Report

Provide a summary showing:

• Total bugs identified
• Already tracked issues (with links)
• Newly created issues (with links)
• Issues needing more information

Example Usage

User: Read this conversation and create issues for any bugs:
[paste conversation]

Agent:
1. Searches for existing issues related to mentioned problems
2. Identifies which bugs are already tracked
3. Creates new issues for untracked bugs
4. Provides summary with all issue links

Best Practices