Bugbot Reference

Complete reference guide for using Bugbot effectively, including workflows and integration patterns

Team Practices

Bugbot-assisted PR Template

## Bug Fix: [Title]

**Original Issue:** #123

**Root Cause:**
[Bugbot's explanation of what was wrong]

**Fix Approach:**
[What was changed and why]

**Bugbot Assistance:**

- Bugbot identified root cause in @[file]
- Bugbot suggested fix approach
- Human refined to handle [edge case]
- Human added [additional test]

**Testing:**

- [x] Added test that reproduces bug
- [x] Verified fix resolves issue
- [x] Ran full test suite (all pass)
- [x] Tested edge cases manually
- [x] No regression in related features

**Review focus:**

- [ ] Does fix address root cause (not symptom)?
- [ ] Are edge cases covered?
- [ ] Business logic correct?

Code review focus:

Root cause correctly identified?
Fix is minimal and targeted?
Tests actually catch the bug?
No new bugs introduced?

When Bugbot Needs Human Pairing

These bugs require human + Bugbot collaboration:

Race conditions - Bugbot can identify, human must verify timing
Memory leaks - Bugbot can spot patterns, human must profile
Integration issues - Bugbot suggests, human tests with real systems
Performance bugs - Bugbot optimizes, human benchmarks
Security issues - Bugbot flags, human does security review

Pattern:

Bugbot: Analyzes + Suggests
Human: Verifies + Tests + Approves

Integration with Bug Tracking

Linear/Jira → Bugbot workflow:

Step 1: Create ticket with Bugbot-friendly format

Title: [BUG] Checkout fails for international addresses

Environment: Production
Severity: High
Affected users: ~15% (international customers)

Reproduction:

1. Add item to cart
2. Enter UK address: "10 Downing St, London, SW1A 2AA"
3. Click checkout
4. Error: "Invalid postal code"

Expected: Should accept UK postal codes
Actual: Rejects with validation error

Stack trace:
[paste from logs]

Related files:

- src/checkout/CheckoutService.ts
- src/validation/AddressValidator.ts

Step 2: Use ticket content with Bugbot

Copy ticket → Paste to Bugbot → Add @file references

Step 3: Link fix back to ticket

PR #456: Fixes #123
- Root cause: US-only postal code validation
- Fix: Added international format support
- Bugbot assistance: Identified issue in 10 min
- Tests: Added for UK, CA, AU, DE, FR formats

Benefits:

Consistent bug report format
Easy to track Bugbot effectiveness
Clear audit trail

Advanced: Bugbot for Performance Issues

Real case: Slow report generation (Client A)

Step 1: Provide profiling data

You: "Report generation is slow (3+ minutes)

Profiling data:
- Database queries: 2.5 minutes (85%)
- Data processing: 0.4 minutes (12%)
- Rendering: 0.1 minutes (3%)

Slow query log:
[paste EXPLAIN ANALYZE output]

Code:
@src/reports/ReportGenerator.ts
@src/reports/ReportService.ts

Help identify performance bottlenecks."

Step 2: Bugbot analyzes

Bugbot identifies:
1. N+1 query pattern (loading related data in loop)
2. Missing indexes on joined tables
3. Processing entire dataset in memory

Step 3: Iterative optimization

You: "Fix issue #1 (N+1 queries) first.
Show me before/after query patterns."

[Bugbot suggests eager loading]

You: "Implement that fix + benchmark it"

[Apply, test, measure: 3min → 45s]

You: "Now fix issue #2 (missing indexes)"

[Bugbot suggests indexes]

You: "Generate CREATE INDEX statements + migration"

[Apply, test, measure: 45s → 20s]

Key: One optimization at a time, measure after each.

Best Practices Summary

Do:

Give clear reproduction steps
Include full error messages and stack traces
Reference specific files with @
Ask for root cause explanation first
Review and test thoroughly
Use rules to guide Bugbot behavior

Don't:

Use for bugs you already understand (slower)
Accept first suggestion without review
Skip testing "because Bugbot did it"
Use for security vulnerabilities (need human review)
Expect Bugbot to know business logic

Remember: Bugbot is a debugging partner, not a magic fix button. The human is still responsible for:

Verifying the fix is correct
Understanding the root cause
Ensuring no regressions
Making final call on approach