lmiranda
2e65b60725
Major refactoring of projman plugin architecture: Skills Extraction (17 new files): - Extracted reusable knowledge from commands and agents into skills/ - branch-security, dependency-management, git-workflow, input-detection - issue-conventions, lessons-learned, mcp-tools-reference, planning-workflow - progress-tracking, repo-validation, review-checklist, runaway-detection - setup-workflows, sprint-approval, task-sizing, test-standards, wiki-conventions Command Consolidation (17 → 12 commands): - /setup: consolidates initial-setup, project-init, project-sync (--full/--quick/--sync) - /debug: consolidates debug-report, debug-review (report/review modes) - /test: consolidates test-check, test-gen (run/gen modes) - /sprint-status: absorbs sprint-diagram via --diagram flag Architecture Cleanup: - Remove plugin-level mcp-servers/ symlinks (6 plugins) - Remove plugin README.md files (12 files, ~2000 lines) - Update all documentation to reflect new command structure - Fix documentation drift in CONFIGURATION.md, COMMANDS-CHEATSHEET.md Commands are now thin dispatchers (~20-50 lines) that reference skills. Agents reference skills for domain knowledge instead of inline content. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
163 lines
4.6 KiB
Markdown
163 lines
4.6 KiB
Markdown
---
|
|
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:
|
|
```env
|
|
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] ║
|
|
╚══════════════════════════════════════════════════════════════════╝
|
|
```
|