leo-claude-mktplace/plugins/projman/commands/debug.md

description

description
Diagnose issues and create reports, or investigate existing diagnostic issues

Debug

Skills Required

• skills/mcp-tools-reference.md
• skills/lessons-learned.md
• skills/git-workflow.md

Purpose

Unified debugging command for diagnostics and issue investigation.

Invocation

/debug              # Ask which mode
/debug report       # Run diagnostics, create issue
/debug review       # Investigate existing issues

Mode Selection

If no subcommand provided, ask user:

1. Report - Run MCP tool diagnostics and create issue in marketplace
2. Review - Investigate existing diagnostic issues and propose fixes

---

Mode: Report

Create structured issues in the marketplace repository.

Prerequisites

Project .env must have:

PROJMAN_MARKETPLACE_REPO=personal-projects/leo-claude-mktplace

Workflow

Step 0: Select Report Type

• Automated - Run MCP tool diagnostics and report failures
• User-Reported - Gather structured feedback about a problem

For User-Reported (Step 0.1)

Gather via AskUserQuestion:

1. Which plugin/command was affected
2. What was the goal
3. What type of problem (error, missing feature, unexpected behavior, docs)
4. Problem description
5. Expected behavior
6. Workaround (optional)

Steps 1-2: Context Gathering

1. Gather project context (git remote, branch, pwd)
2. Detect sprint context (active milestone)
3. Read marketplace config

Steps 3-4: Diagnostic Suite (Automated Only)

Run MCP tools with explicit repo parameter:

• validate_repo_org
• get_labels
• list_issues
• list_milestones
• suggest_labels

Categorize: Parameter Format, Authentication, Not Found, Network, Logic

Steps 5-6: Generate Labels and Issue

Automated: Type/Bug, Source/Diagnostic, Agent/Claude + suggested User-Reported: Map problem type to labels

Step 7: Create Issue

Use curl (not MCP) - avoids branch protection issues

Step 8: Report to User

Show summary and link to created issue

DO NOT (Report Mode)

• Attempt to fix anything - only report
• Create issues if all automated tests pass (unless user-reported)
• Use MCP tools to create issues in marketplace - always use curl

---

Mode: Review

Investigate diagnostic issues and propose fixes with human approval.

Workflow with Approval Gates

Steps 1-8: Investigation

1. Detect repository (git remote)
2. Fetch diagnostic issues: list_issues(labels=["Source: Diagnostic"])
3. Display issue list
4. User selects issue (AskUserQuestion)
5. Fetch full details: get_issue(issue_number=...)
6. Parse diagnostic report (failed tools, errors, hypothesis)
7. Map errors to files
8. Read relevant files - MANDATORY before proposing fix

Step 9: Investigation Summary

Present analysis to user.

APPROVAL GATE 1: "Does this analysis match your understanding?"

• STOP and wait for user response

Step 9.5: Search Lessons Learned

Search for related past fixes using search_lessons.

Step 10: Propose Fix

Present specific fix approach with changes and rationale.

APPROVAL GATE 2: "Proceed with this fix?"

• STOP and wait for user response

Steps 11-12: Implement

1. Create feature branch (fix/issue-N-description)
2. Make code changes
3. Run tests
4. Show diff to user

APPROVAL GATE 3: "Create PR with these changes?"

• STOP and wait for user response

Steps 13-15: Finalize

13. Commit and push
14. Create PR
15. After user verifies fix: Close issue (REQUIRED) and capture lesson

Error-to-File Quick Reference

Error Pattern	Check Files
"owner/repo format"	config.py, gitea_client.py
"404" + "orgs"	gitea_client.py
"401", "403"	config.py (token)
"No repository"	Command .md file

DO NOT (Review Mode)

• Skip reading relevant files
• Proceed past approval gates without confirmation
• Close issues until user confirms fix works
• Commit directly to development/main

---

Visual Output

╔══════════════════════════════════════════════════════════════════╗
║  📋 PROJMAN                                                      ║
║  🔧 DEBUG                                                        ║
║  [Mode: Report | Review]                                         ║
╚══════════════════════════════════════════════════════════════════╝