bobmatnyc/claude-mpm/mpm-bug-reporting

Name: mpm-bug-reporting
Author: bobmatnyc

Claude Code and agent skill by bobmatnyc/claude-mpm

Trust tier 3

community

By bobmatnyc
Coding
bobmatnyc/claude-mpm
src/claude_mpm/skills/bundled/pm/mpm-bug-reporting/SKILL.md
Updated 23 Mar 2026
Version 1.0.0

Source check pending

Checking that the SKILL.md file is still in the repository.

Bug reporting protocol for PM and agents to file GitHub issues

Install

npx vskill@latest install bobmatnyc/claude-mpm/mpm-bug-reporting

SKILL.md

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:

Bug Type	Repository	Owner/Repo
Core MPM (CLI, startup, config, orchestration)	claude-mpm	bobmatnyc/claude-mpm
Agent bugs (wrong behavior, errors, missing capabilities)	claude-mpm-agents	bobmatnyc/claude-mpm-agents
Skill bugs (wrong info, outdated, missing content)	claude-mpm-skills	bobmatnyc/claude-mpm-skills

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

markdown

## 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

bash

gh auth status

If not authenticated:

bash

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:

Log locally for manual reporting:

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

Report to PM for alternative action:

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

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

Security

Security scanPassed, 90 of 100Pattern checks on the skill's files.
Model reviewPassed

See the full security report

Quality evaluation

Task evaluationNot runNo evaluation yet. Run one in Skill Studio.

See evaluation results

Source

SKILL.md in the repositoryCheckingsrc/claude_mpm/skills/bundled/pm/mpm-bug-reporting/SKILL.md

Popularity

Repository stars: 92
Repository forks: 18
Repository npm downloads, 7 days: 707
7-day trend score: 39

Stars and forks are for the whole GitHub repository, not this skill alone. Downloads are for the repository's npm package. Refreshed 23 Mar 2026, 7 months ago.

Works with

Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.

Claude Code
Cursor
GitHub Copilot
Windsurf
Codex
Gemini CLI
Cline
Amp
Roo Code
Goose
Continue
Kilo Code
Junie
Trae
OpenHands
Qwen Code
AI Agent
Tabnine Chat
Sourcegraph Cody
Amazon Q
Firebase Genkit
Sweep
Devin
Phind
Mentat
Claude Desktop
Aider
GPT Pilot
Plandex
bolt.new
v0
Replit Agent
Anse
TypingMind
BetterChatGPT
LibreChat
Warp AI
Pieces
Fig AI

Embed badge

[![vskill VERIFIED](https://verified-skill.com/api/v1/skills/bobmatnyc/claude-mpm/mpm-bug-reporting/badge)](https://verified-skill.com/skills/bobmatnyc/claude-mpm/mpm-bug-reporting)

Something wrong with this skill or its page? Tell us.