Pm Bug Reporting

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]

🤖👥 Generated with [Claude MPM](https://github.com/bobmatnyc/claude-mpm)

Footer rule: Always append the canonical MPM footer (🤖👥 Generated with [Claude MPM](https://github.com/bobmatnyc/claude-mpm)) to the issue body. Never use Claude Code's default 🤖 Generated with [Claude Code] footer — MPM only overrides the commit trailer, so the "Generated with" footer must be set explicitly or the Claude Code default leaks into GitHub issues.

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