Monday Bug Fixer Guru

An agent specialized in transforming incomplete bug reports into comprehensive fixes by leveraging Monday.com's project management context, gathering related items, historical fixes, documentation, and stakeholder comments to understand root causes and deliver targeted, well-tested pull requests.

When to Use This Agent

Choose Monday Bug Fixer Guru when:

• Fixing bugs reported through Monday.com boards with linked context
• Investigating issues that need cross-referencing with project history
• Building fixes that need to align with epic goals and sprint priorities
• Creating comprehensive PR descriptions from Monday.com bug tickets
• Tracing bugs through related items, subitems, and linked documentation

Consider alternatives when:

• Fixing bugs without Monday.com integration (use a standard debugging agent)
• Doing project management without code fixes (use Monday.com directly)
• Building new features that aren't bug-related (use a development agent)

Quick Start

Copy
# .claude/agents/monday-bug-fixer-guru.yml
name: Monday Bug Fixer Guru
model: claude-sonnet-4-20250514
tools:
  - Read
  - Write
  - Bash
  - Glob
  - Grep
prompt: |
  You are a bug-fixing specialist who uses Monday.com context
  to build comprehensive fixes. Gather all context from related
  items, historical fixes, and stakeholder comments before
  writing code. Every fix should address root cause, not symptoms.
  One shot, one PR — make it count.

Example invocation:

Copy
claude --agent monday-bug-fixer-guru "Fix the bug in Monday item
  #4521 - payment processing fails for international cards.
  Check related items and recent changes to the payment module."

Core Concepts

Context Gathering Workflow

Monday Item → Related Items → Historical Fixes → Documentation
     │              │                │                 │
  Bug report    Linked items    Git blame/log     Wiki pages
  Comments      Parent epic     Similar PRs       API docs
  Status log    Subitems        Revert history    Config docs
  Assignees     Dependencies    Test failures     Runbooks

Bug Investigation Framework

Phase	Actions	Output
Gather	Read bug report, comments, related items	Context document
Reproduce	Set up test case that triggers the bug	Failing test
Isolate	Trace code path, review recent changes	Root cause
Fix	Implement minimal change addressing root cause	Code change
Verify	Run tests, check edge cases, review impact	Test results
Document	PR description, Monday item update	PR + status update

Root Cause Analysis Template

Copy
## Bug Analysis: #{ITEM_ID}

### Symptom
What the user reported / what's visibly broken

### Reproduction
Steps to reproduce + minimal test case

### Root Cause
The actual code defect (not the symptom)

### Recent Changes
Git commits in the affected area (last 2 weeks)

### Related Issues
Monday items with similar symptoms or in the same module

### Fix Strategy
Minimal change that addresses root cause

### Risk Assessment
What else could this fix affect?

### Test Coverage
New tests + existing tests that validate the fix

Configuration

Parameter	Description	Default
monday_board_id	Default Monday.com board to query	From env
git_blame_depth	How far back to search git history	30 days
related_items_depth	Levels of related items to traverse	2
pr_template	Pull request description template	Built-in
auto_update_status	Update Monday item status automatically	false
test_requirement	Require tests with every fix	true
review_assignment	Auto-assign PR reviewers	From Monday assignees

Best Practices

1. Gather all context before writing a single line of code. Read the bug report, every comment, all related Monday items, the parent epic goals, and recent git history in the affected area. Context that seems tangential often reveals the root cause: a comment from three weeks ago mentioning "this might break if..." frequently points directly to the problem. Thorough context gathering prevents fixing symptoms instead of causes.

2. Write a failing test before implementing the fix. Create a test that reproduces the exact bug condition. This test should fail on the current code and pass after your fix. The test serves three purposes: it proves the bug exists, it proves the fix works, and it prevents the bug from recurring. If you can't write a test that reproduces the bug, you don't understand the bug well enough to fix it.

3. Make the smallest possible change that addresses the root cause. Resist the urge to refactor surrounding code, improve naming, or fix other issues you discover. Each additional change increases review complexity and regression risk. File separate Monday items for other improvements. A focused fix is easier to review, easier to revert if needed, and easier to understand months later when someone reads the git history.

4. Link everything bidirectionally. The PR should reference the Monday item. The Monday item should link to the PR. Related items should cross-reference each other. The commit message should include the item number. This linking creates a traceable chain from bug report through investigation to fix, which is invaluable for future debugging of related issues and for understanding the project's bug history.

5. Update the Monday item with investigation findings, not just the fix. Document what you discovered during investigation: the root cause, why it wasn't caught earlier, what related code might have similar issues, and whether the fix is a permanent solution or a temporary patch. This context helps product managers prioritize related work and helps future developers understand the codebase's known problem areas.

Common Issues

Bug report lacks sufficient information to reproduce. Check Monday item comments, activity log, and related items for additional context. Look at the reporter's other bug reports for patterns. Examine server logs and error tracking tools for the reported timeframe. If reproduction still isn't possible, add a comment to the Monday item with specific questions and the information needed, rather than guessing at a fix that might address the wrong problem.

Fix addresses the symptom but not the root cause. This manifests as the same bug reappearing in slightly different forms. Before implementing, ask "why did this happen?" recursively until you reach a code-level cause. If a null pointer exception occurs because a function returns null, don't just add a null check—understand why the function returns null and fix that. The null check may be appropriate as defense in depth, but it's not the fix.

Related Monday items reveal the bug affects more areas than initially reported. When investigation shows broader impact, resist the urge to fix everything in one PR. Document the full scope in the Monday item, fix the originally reported issue first, then create separate items for each additional affected area. This approach delivers value quickly while ensuring each fix gets proper review and testing.