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

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

**First, check if MCP tools are available.** Attempt to use an MCP tool. If you receive "tool not found", "not in function list", or similar error, the MCP server is not accessible in this session - use the curl fallback.

#### Option A: MCP Available (preferred)

```
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.

#### Option B: MCP Unavailable - Use curl Fallback

If MCP tools are not available (the very issue you may be diagnosing), use this fallback:

**1. Check for Gitea credentials:**

```bash
if [[ -f ~/.config/claude/gitea.env ]]; then
  source ~/.config/claude/gitea.env
  echo "Credentials found. API URL: $GITEA_API_URL"
else
  echo "No credentials at ~/.config/claude/gitea.env"
fi
```

**2. If credentials exist, create issue via curl with proper JSON escaping:**

Create secure temp files and save content:

```bash
# Create temp files with restrictive permissions
DIAG_TITLE=$(mktemp -p /tmp -m 600 diag-title.XXXXXX)
DIAG_BODY=$(mktemp -p /tmp -m 600 diag-body.XXXXXX)
DIAG_PAYLOAD=$(mktemp -p /tmp -m 600 diag-payload.XXXXXX)

# Save title
echo "[Diagnostic] [summary of main failure]" > "$DIAG_TITLE"

# Save body (paste Step 5 content) - heredoc delimiter prevents shell expansion
cat > "$DIAG_BODY" << 'DIAGNOSTIC_EOF'
[Paste the full issue content from Step 5 here]
DIAGNOSTIC_EOF
```

Construct JSON safely using jq's --rawfile (avoids command substitution):

```bash
# Build JSON payload using jq with --rawfile for safe content handling
jq -n \
  --rawfile title "$DIAG_TITLE" \
  --rawfile body "$DIAG_BODY" \
  '{title: ($title | rtrimstr("\n")), body: $body}' > "$DIAG_PAYLOAD"

# Create issue using the JSON file
curl -s -X POST "${GITEA_API_URL}/repos/${MARKETPLACE_REPO}/issues" \
  -H "Authorization: token ${GITEA_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d @"$DIAG_PAYLOAD" | jq '.html_url // .'

# Secure cleanup
rm -f "$DIAG_TITLE" "$DIAG_BODY" "$DIAG_PAYLOAD"
```

**3. If no credentials found, save report locally:**

```bash
REPORT_FILE=$(mktemp -p /tmp -m 600 diagnostic-report-XXXXXX.md)
cat > "$REPORT_FILE" << 'DIAGNOSTIC_EOF'
[Paste the full issue content from Step 5 here]
DIAGNOSTIC_EOF
echo "Report saved to: $REPORT_FILE"
```

Then inform the user:

```
MCP tools are unavailable and no Gitea credentials found at ~/.config/claude/gitea.env.

Diagnostic report saved to: [REPORT_FILE]

To create the issue manually:
1. Configure credentials: See docs/CONFIGURATION.md
2. Or create issue directly at: http://gitea.hotserv.cloud/[MARKETPLACE_REPO]/issues/new
```

### 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**
- Use the curl fallback in Step 6, Option B
- Requires Gitea credentials at `~/.config/claude/gitea.env`
- If no credentials, report will be saved locally for manual submission