| name | pm-bug-reporting |
| version | 1.0.0 |
| description | Bug reporting protocol for PM and agents to file GitHub issues |
| when_to_use | Framework bugs, agent errors, skill content errors detected |
| category | pm-workflow |
| tags | ["bug-reporting","github","issues","pm-required"] |
Report bugs when you encounter:
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 |
Decision tree:
bobmatnyc/claude-mpmbobmatnyc/claude-mpm-agentsbobmatnyc/claude-mpm-skillsExternal systems installed via claude-mpm setup:
kuzu-memory → File issue at kuzu-memory's GitHubmcp-vector-search → File issue at mcp-vector-search's GitHubslack-user-proxy → File issue at slack-user-proxy's GitHubgoogle-workspace-mpm → File issue at google-workspace-mpm's GitHubExamples:
When creating an issue, include:
Brief, descriptive title (50 chars max)
Always include:
bug (required)agent-reported (required)high-priority - Critical functionality brokendocumentation - Documentation erroragent-error - Agent-specific issueskill-error - Skill content issue## 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]
gh auth status
If not authenticated:
gh auth login
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]
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.
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.
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.
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."
Bug reporting successful when:
bug, agent-reported)PM MUST:
Build MCP (Model Context Protocol) servers - expose tools, resources, and prompts to LLMs. TypeScript/Python SDKs for Claude Desktop integration. NOTE: Do NOT invoke for the built-in /mcp Claude Code command — that lists configured MCP servers and is unrelated to building MCP server code.
MCP (Model Context Protocol) server build and evaluation guide, including local conventions for tool surfaces, config, and testing
Guide for creating effective skills
Re-authenticate Google Workspace MCP in-flight - refresh tokens, setup OAuth, check status
Protocol for tracking files immediately after agent creation
Send cross-project messages to other Claude MPM instances