feat: add debug workflow commands and bump to v3.1.0
New commands for structured debugging workflow: /debug-report (for test projects): - Runs 5 diagnostic MCP tool tests - Captures full project context (git remote, cwd, branch) - Generates structured issue with hypothesis - Creates issue in marketplace repo automatically /debug-review (for marketplace repo): - Lists open diagnostic issues for triage - Maps errors to relevant code files - MANDATORY: Reads files before proposing fixes - Three human approval gates - Creates feature branch, commits, PR with linking Also includes: - Dynamic label format detection in suggest_labels - Rewritten labels-sync.md with explicit execution steps - Version bump to 3.1.0 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
262
plugins/projman/commands/debug-report.md
Normal file
262
plugins/projman/commands/debug-report.md
Normal file
@@ -0,0 +1,262 @@
|
||||
---
|
||||
description: Run diagnostics and create structured issue in marketplace repository
|
||||
---
|
||||
|
||||
# Debug Report
|
||||
|
||||
Run diagnostic checks on projman MCP tools and create a structured issue in the marketplace repository for investigation.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Your project `.env` must have:
|
||||
|
||||
```env
|
||||
PROJMAN_MARKETPLACE_REPO=personal-projects/leo-claude-mktplace
|
||||
```
|
||||
|
||||
If not configured, ask the user for the marketplace repository path.
|
||||
|
||||
## CRITICAL: Execution Steps
|
||||
|
||||
You MUST follow these steps in order. Do NOT skip any step.
|
||||
|
||||
### Step 1: Gather Project Context
|
||||
|
||||
Run these Bash commands to capture project information:
|
||||
|
||||
```bash
|
||||
# Get git remote URL
|
||||
git remote get-url origin
|
||||
|
||||
# Get current branch
|
||||
git branch --show-current
|
||||
|
||||
# Get working directory
|
||||
pwd
|
||||
```
|
||||
|
||||
Parse the git remote to extract `REPO_NAME` in `owner/repo` format.
|
||||
|
||||
Store all values:
|
||||
- `PROJECT_REPO`: The detected owner/repo
|
||||
- `GIT_REMOTE`: Full git remote URL
|
||||
- `CURRENT_BRANCH`: Current branch name
|
||||
- `WORKING_DIR`: Current working directory
|
||||
|
||||
### Step 2: Read Marketplace Configuration
|
||||
|
||||
```bash
|
||||
grep PROJMAN_MARKETPLACE_REPO .env
|
||||
```
|
||||
|
||||
Store as `MARKETPLACE_REPO`. If not found, ask the user.
|
||||
|
||||
### Step 3: Run Diagnostic Suite
|
||||
|
||||
Run each MCP tool with explicit `repo` parameter. Record success/failure and full response.
|
||||
|
||||
**Test 1: validate_repo_org**
|
||||
```
|
||||
mcp__plugin_projman_gitea__validate_repo_org(repo=PROJECT_REPO)
|
||||
```
|
||||
Expected: `{is_organization: true/false}`
|
||||
|
||||
**Test 2: get_labels**
|
||||
```
|
||||
mcp__plugin_projman_gitea__get_labels(repo=PROJECT_REPO)
|
||||
```
|
||||
Expected: `{organization: [...], repository: [...], total_count: N}`
|
||||
|
||||
**Test 3: list_issues**
|
||||
```
|
||||
mcp__plugin_projman_gitea__list_issues(repo=PROJECT_REPO, state="open")
|
||||
```
|
||||
Expected: Array of issues
|
||||
|
||||
**Test 4: list_milestones**
|
||||
```
|
||||
mcp__plugin_projman_gitea__list_milestones(repo=PROJECT_REPO)
|
||||
```
|
||||
Expected: Array of milestones
|
||||
|
||||
**Test 5: suggest_labels**
|
||||
```
|
||||
mcp__plugin_projman_gitea__suggest_labels(context="Test bug fix for authentication")
|
||||
```
|
||||
Expected: Array of label names matching repo's format
|
||||
|
||||
For each test, record:
|
||||
- Tool name
|
||||
- Exact parameters used
|
||||
- Status: PASS or FAIL
|
||||
- Response or error message
|
||||
|
||||
### Step 4: Analyze Results
|
||||
|
||||
Count failures and categorize errors:
|
||||
|
||||
| Category | Indicators |
|
||||
|----------|------------|
|
||||
| Parameter Format | "owner/repo format", "missing parameter" |
|
||||
| Authentication | "401", "403", "unauthorized" |
|
||||
| Not Found | "404", "not found" |
|
||||
| Network | "connection", "timeout", "ECONNREFUSED" |
|
||||
| Logic | Unexpected response format, wrong data |
|
||||
|
||||
For each failure, write a hypothesis about the likely cause.
|
||||
|
||||
### Step 5: Generate Issue Content
|
||||
|
||||
Use this exact template:
|
||||
|
||||
```markdown
|
||||
## Diagnostic Report
|
||||
|
||||
**Generated**: [ISO timestamp]
|
||||
**Command Tested**: [What the user was trying to run, or "general diagnostic"]
|
||||
**Reporter**: Claude Code via /debug-report
|
||||
|
||||
## Project Context
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| Repository | `[PROJECT_REPO]` |
|
||||
| Git Remote | `[GIT_REMOTE]` |
|
||||
| Working Directory | `[WORKING_DIR]` |
|
||||
| Current Branch | `[CURRENT_BRANCH]` |
|
||||
|
||||
## Diagnostic Results
|
||||
|
||||
### Test 1: validate_repo_org
|
||||
|
||||
**Call**: `validate_repo_org(repo="[PROJECT_REPO]")`
|
||||
**Status**: [PASS/FAIL]
|
||||
**Response**:
|
||||
```json
|
||||
[full response or error]
|
||||
```
|
||||
|
||||
### Test 2: get_labels
|
||||
|
||||
**Call**: `get_labels(repo="[PROJECT_REPO]")`
|
||||
**Status**: [PASS/FAIL]
|
||||
**Response**:
|
||||
```json
|
||||
[full response or error - truncate if very long]
|
||||
```
|
||||
|
||||
[... repeat for each test ...]
|
||||
|
||||
## Summary
|
||||
|
||||
- **Total Tests**: 5
|
||||
- **Passed**: [N]
|
||||
- **Failed**: [N]
|
||||
|
||||
### Failed Tools
|
||||
|
||||
[List each failed tool with its error]
|
||||
|
||||
### Error Category
|
||||
|
||||
[Check applicable categories]
|
||||
|
||||
### Hypothesis
|
||||
|
||||
[Your analysis of what's wrong and why]
|
||||
|
||||
### Suggested Investigation
|
||||
|
||||
1. [First file/function to check]
|
||||
2. [Second file/function to check]
|
||||
3. [etc.]
|
||||
|
||||
## Reproduction Steps
|
||||
|
||||
1. Navigate to `[WORKING_DIR]`
|
||||
2. Run `[command that was being tested]`
|
||||
3. Observe error at step [X]
|
||||
|
||||
---
|
||||
|
||||
*Generated by /debug-report - Labels: Type: Bug, Source: Diagnostic, Agent: Claude*
|
||||
```
|
||||
|
||||
### Step 6: Create Issue in Marketplace
|
||||
|
||||
```
|
||||
mcp__plugin_projman_gitea__create_issue(
|
||||
repo=MARKETPLACE_REPO,
|
||||
title="[Diagnostic] [summary of main failure]",
|
||||
body=[generated content from Step 5],
|
||||
labels=["Type: Bug", "Source: Diagnostic", "Agent: Claude"]
|
||||
)
|
||||
```
|
||||
|
||||
If labels don't exist, create issue without labels.
|
||||
|
||||
### Step 7: Report to User
|
||||
|
||||
Display summary:
|
||||
|
||||
```
|
||||
Debug Report Complete
|
||||
=====================
|
||||
|
||||
Project: [PROJECT_REPO]
|
||||
Tests Run: 5
|
||||
Passed: [N]
|
||||
Failed: [N]
|
||||
|
||||
Failed Tools:
|
||||
- [tool1]: [brief error]
|
||||
- [tool2]: [brief error]
|
||||
|
||||
Issue Created: [issue URL]
|
||||
|
||||
Next Steps:
|
||||
1. Switch to marketplace repo: cd [marketplace path]
|
||||
2. Run: /debug-review
|
||||
3. Select issue #[N] to investigate
|
||||
```
|
||||
|
||||
## DO NOT
|
||||
|
||||
- **DO NOT** attempt to fix anything - only report
|
||||
- **DO NOT** create issues if all tests pass (just report success)
|
||||
- **DO NOT** skip any diagnostic test
|
||||
- **DO NOT** call MCP tools without the `repo` parameter
|
||||
- **DO NOT** ask user questions during execution - run autonomously
|
||||
|
||||
## If All Tests Pass
|
||||
|
||||
If all 5 tests pass, report success without creating an issue:
|
||||
|
||||
```
|
||||
Debug Report Complete
|
||||
=====================
|
||||
|
||||
Project: [PROJECT_REPO]
|
||||
Tests Run: 5
|
||||
Passed: 5
|
||||
Failed: 0
|
||||
|
||||
All diagnostics passed. No issues to report.
|
||||
|
||||
If you're experiencing a specific problem, please describe it
|
||||
and I can create a manual bug report.
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
**PROJMAN_MARKETPLACE_REPO not configured**
|
||||
- Ask user: "What is the marketplace repository? (e.g., personal-projects/leo-claude-mktplace)"
|
||||
- Store for this session and remind user to add to .env
|
||||
|
||||
**Cannot detect project repository**
|
||||
- Check if in a git repository: `git rev-parse --git-dir`
|
||||
- If not a git repo, ask user for the repository path
|
||||
|
||||
**MCP tools not available**
|
||||
- The projman plugin may not be properly installed
|
||||
- Check if .mcp.json exists and is configured
|
||||
Reference in New Issue
Block a user