PM Bug Reporting Protocol

When to Report Bugs

Report bugs when you encounter:

• PM instruction errors or missing guidance
• Agent malfunction or incorrect behavior
• Skill content errors or outdated information
• Framework crashes or unexpected behavior
• Missing or incorrect documentation
• Configuration errors or invalid defaults

GitHub Repositories

Route bugs to the correct repository:

External System Bug Routing

Decision tree:

• Bug in MPM startup/config/delegation → bobmatnyc/claude-mpm
• Bug in agent behavior → bobmatnyc/claude-mpm-agents
• Bug in skill content → bobmatnyc/claude-mpm-skills
• Bug in external system (installed via setup) → That system's GitHub repo

External systems installed via claude-mpm setup:

• kuzu-memory → File issue at kuzu-memory's GitHub
• mcp-vector-search → File issue at mcp-vector-search's GitHub
• slack-user-proxy → File issue at slack-user-proxy's GitHub
• google-workspace-mpm → File issue at google-workspace-mpm's GitHub
• Other MCP servers → Check their GitHub repos

Examples:

• "Vector search returns no results" → mcp-vector-search repo
• "Kuzu memory fails to persist" → kuzu-memory repo
• "PM fails to delegate" → claude-mpm repo
• "Research agent crashes" → claude-mpm-agents repo

Bug Report Template

When creating an issue, include:

Title

Brief, descriptive title (50 chars max)

• ✅ "PM delegates to non-existent agent"
• ✅ "Research skill missing web search examples"
• ❌ "Bug in system"
• ❌ "Fix this"

Labels

Always include:

• bug (required)
• agent-reported (required)
• Additional context labels:
  • high-priority - Critical functionality broken
  • documentation - Documentation error
  • agent-error - Agent-specific issue
  • skill-error - Skill content issue

Body Structure

## What Happened
[Clear description of the bug]

## Expected Behavior
[What should have happened]

## Steps to Reproduce
1. [First step]
2. [Second step]
3. [Third step]

## Context
- Agent: [agent name if applicable]
- Skill: [skill name if applicable]
- Error Message: [full error if available]
- Version: [MPM version if known]

## Impact
[How this affects users/workflow]

Using gh CLI

Prerequisites Check

gh auth status

If not authenticated:

gh auth login

Creating Issues

Delegate to ticketing agent with:

Task:
  agent: ticketing
  task: Create GitHub issue for [bug type]
  context: |
    Repository: bobmatnyc/claude-mpm[-agents|-skills]
    Title: [brief title]
    Labels: bug, agent-reported
    Body: |
      ## What Happened
      [description]

      ## Expected Behavior
      [expected]

      ## Steps to Reproduce
      1. [step 1]
      2. [step 2]

      ## Context
      - Agent: [agent name]
      - Error: [error message]

      ## Impact
      [impact description]

Examples

Core MPM Bug

Task:
  agent: ticketing
  task: Create GitHub issue for core MPM bug
  context: |
    Repository: bobmatnyc/claude-mpm
    Title: PM fails to load configuration on startup
    Labels: bug, agent-reported, high-priority
    Body: |
      ## What Happened
      PM fails to initialize when configuration.yaml contains invalid syntax.
      No clear error message shown to user.

      ## Expected Behavior
      PM should display clear YAML syntax error with line number and fix suggestion.

      ## Steps to Reproduce
      1. Add invalid YAML to .claude-mpm/configuration.yaml
      2. Run `mpm`
      3. Observe generic error without details

      ## Context
      - Component: Configuration loader
      - Error: "Failed to load configuration"
      - Version: 5.4.x

      ## Impact
      Users cannot diagnose configuration errors, requiring manual YAML validation.

Agent Bug

Task:
  agent: ticketing
  task: Create GitHub issue for agent bug
  context: |
    Repository: bobmatnyc/claude-mpm-agents
    Title: Research agent fails to search with special characters
    Labels: bug, agent-reported, agent-error
    Body: |
      ## What Happened
      Research agent throws error when search query contains quotes or special chars.

      ## Expected Behavior
      Search queries should be properly escaped and executed.

      ## Steps to Reproduce
      1. Delegate to research: "Search for 'React hooks'"
      2. Research agent attempts search
      3. Error: "Invalid search query"

      ## Context
      - Agent: research
      - Error: grep command fails with unescaped quotes

      ## Impact
      Cannot search for quoted phrases or technical terms with special characters.

Skill Bug

Task:
  agent: ticketing
  task: Create GitHub issue for skill content error
  context: |
    Repository: bobmatnyc/claude-mpm-skills
    Title: Git workflow skill contains outdated branch strategy
    Labels: bug, agent-reported, documentation, skill-error
    Body: |
      ## What Happened
      Skill recommends `git flow` branching model, which project no longer uses.
      Current standard is trunk-based development.

      ## Expected Behavior
      Skill should document current trunk-based workflow.

      ## Context
      - Skill: git-workflow.md
      - Section: "Branching Strategy"
      - Line: 45-60

      ## Impact
      Agents follow outdated branching model, creating workflow friction.

Escalation Path

When ticketing agent is unavailable or gh CLI fails:

1. Log locally for manual reporting:

   echo "[BUG] $(date): [description]" >> .claude-mpm/logs/bugs.log
   

2. Report to PM for alternative action:

   PM should create ticket in primary ticketing system (Linear/JIRA)
   with note to create GitHub issue once available
   

3. User notification:

   "Bug detected: [description]. Logged for manual GitHub issue creation."
   

Success Criteria

Bug reporting successful when:

• ✅ Issue created in correct repository
• ✅ All required labels applied (bug, agent-reported)
• ✅ Body follows template structure
• ✅ Title is clear and concise
• ✅ Context includes agent/skill name if applicable
• ✅ Issue URL returned for tracking

PM Enforcement

PM MUST:

• Detect bugs during agent interactions
• Delegate bug reporting to ticketing agent
• NOT attempt to create GitHub issues directly
• Follow escalation path if ticketing unavailable
• Log all bug reports for audit trail

Related Skills

• pm-ticketing-integration.md - Ticket delegation patterns
• pm-delegation-patterns.md - General delegation guidance
• ticketing-examples.md - Ticketing delegation examples