feat: enhance debug commands with sprint awareness and lessons learned
Debug Report (/debug-report): - Add Step 1.5: Sprint context detection based on branch and milestone - Add Step 5: Smart labeling via suggest_labels MCP tool - Update issue creation to support milestone association Debug Review (/debug-review): - Add Step 9.5: Search lessons learned before proposing fixes - Add Step 15: Verify, close issue, and optionally capture lesson Hooks: - Simplify doc-guardian hook to be truly non-blocking (15 words max) - Update code-sentinel to skip docs/config files entirely Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
@@ -43,6 +43,46 @@ Store all values:
|
||||
- `CURRENT_BRANCH`: Current branch name
|
||||
- `WORKING_DIR`: Current working directory
|
||||
|
||||
### Step 1.5: Detect Sprint Context
|
||||
|
||||
Determine if this debug issue should be associated with an active sprint.
|
||||
|
||||
**1. Check for active sprint milestone:**
|
||||
|
||||
```
|
||||
mcp__plugin_projman_gitea__list_milestones(repo=PROJECT_REPO, state="open")
|
||||
```
|
||||
|
||||
Store the first open milestone as `ACTIVE_SPRINT` (if any).
|
||||
|
||||
**2. Analyze branch context:**
|
||||
|
||||
| Branch Pattern | Context |
|
||||
|----------------|---------|
|
||||
| `feat/*`, `fix/*`, `issue-*` | Sprint work - likely related to current sprint |
|
||||
| `main`, `master`, `development` | Production/standalone - not sprint-related |
|
||||
| Other | Unknown - ask user |
|
||||
|
||||
**3. Determine sprint association:**
|
||||
|
||||
```
|
||||
IF ACTIVE_SPRINT exists AND CURRENT_BRANCH matches sprint pattern (feat/*, fix/*, issue-*):
|
||||
→ SPRINT_CONTEXT = "detected"
|
||||
→ Ask user: "Active sprint detected: [SPRINT_NAME]. Is this bug related to sprint work?"
|
||||
Options:
|
||||
- Yes, add to sprint (will associate with milestone)
|
||||
- No, standalone fix (no milestone)
|
||||
→ Store choice as ASSOCIATE_WITH_SPRINT (true/false)
|
||||
|
||||
ELSE IF ACTIVE_SPRINT exists AND CURRENT_BRANCH is main/development:
|
||||
→ SPRINT_CONTEXT = "production"
|
||||
→ ASSOCIATE_WITH_SPRINT = false (standalone fix, no question needed)
|
||||
|
||||
ELSE:
|
||||
→ SPRINT_CONTEXT = "none"
|
||||
→ ASSOCIATE_WITH_SPRINT = false
|
||||
```
|
||||
|
||||
### Step 2: Read Marketplace Configuration
|
||||
|
||||
```bash
|
||||
@@ -105,7 +145,42 @@ Count failures and categorize errors:
|
||||
|
||||
For each failure, write a hypothesis about the likely cause.
|
||||
|
||||
### Step 5: Generate Issue Content
|
||||
### Step 5: Generate Smart Labels
|
||||
|
||||
Generate appropriate labels based on the diagnostic results.
|
||||
|
||||
**1. Build context string for label suggestion:**
|
||||
|
||||
```
|
||||
LABEL_CONTEXT = "Bug fix: " + [summary of main failure] + ". " +
|
||||
"Failed tools: " + [list of failed tool names] + ". " +
|
||||
"Error category: " + [detected error category from Step 4]
|
||||
```
|
||||
|
||||
**2. Get suggested labels:**
|
||||
|
||||
```
|
||||
mcp__plugin_projman_gitea__suggest_labels(
|
||||
repo=PROJECT_REPO,
|
||||
context=LABEL_CONTEXT
|
||||
)
|
||||
```
|
||||
|
||||
**3. Merge with base labels:**
|
||||
|
||||
```
|
||||
BASE_LABELS = ["Type: Bug", "Source: Diagnostic", "Agent: Claude"]
|
||||
SUGGESTED_LABELS = [result from suggest_labels]
|
||||
|
||||
# Combine, avoiding duplicates
|
||||
FINAL_LABELS = BASE_LABELS + [label for label in SUGGESTED_LABELS if label not in BASE_LABELS]
|
||||
```
|
||||
|
||||
The final label set should include:
|
||||
- **Always**: `Type: Bug`, `Source: Diagnostic`, `Agent: Claude`
|
||||
- **If detected**: `Component: *`, `Complexity: *`, `Risk: *`, `Priority: *`
|
||||
|
||||
### Step 6: Generate Issue Content
|
||||
|
||||
Use this exact template:
|
||||
|
||||
@@ -182,22 +257,36 @@ Use this exact template:
|
||||
*Generated by /debug-report - Labels: Type: Bug, Source: Diagnostic, Agent: Claude*
|
||||
```
|
||||
|
||||
### Step 6: Create Issue in Marketplace
|
||||
### Step 7: 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)
|
||||
|
||||
**If ASSOCIATE_WITH_SPRINT is true:**
|
||||
|
||||
```
|
||||
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"]
|
||||
body=[generated content from Step 6],
|
||||
labels=FINAL_LABELS,
|
||||
milestone=ACTIVE_SPRINT.id
|
||||
)
|
||||
```
|
||||
|
||||
If labels don't exist, create issue without labels.
|
||||
**If ASSOCIATE_WITH_SPRINT is false (standalone fix):**
|
||||
|
||||
```
|
||||
mcp__plugin_projman_gitea__create_issue(
|
||||
repo=MARKETPLACE_REPO,
|
||||
title="[Diagnostic] [summary of main failure]",
|
||||
body=[generated content from Step 6],
|
||||
labels=FINAL_LABELS
|
||||
)
|
||||
```
|
||||
|
||||
If some labels don't exist, create issue with available labels only.
|
||||
|
||||
#### Option B: MCP Unavailable - Use curl Fallback
|
||||
|
||||
@@ -274,7 +363,7 @@ To create the issue manually:
|
||||
2. Or create issue directly at: http://gitea.hotserv.cloud/[MARKETPLACE_REPO]/issues/new
|
||||
```
|
||||
|
||||
### Step 7: Report to User
|
||||
### Step 8: Report to User
|
||||
|
||||
Display summary:
|
||||
|
||||
|
||||
@@ -195,6 +195,74 @@ Does this analysis match your understanding of the problem?
|
||||
|
||||
Do NOT proceed until user approves.
|
||||
|
||||
### Step 9.5: Search Lessons Learned
|
||||
|
||||
Before proposing a fix, search for relevant lessons from past fixes.
|
||||
|
||||
**1. Extract search tags from the issue:**
|
||||
|
||||
```
|
||||
SEARCH_TAGS = []
|
||||
# Add tool names
|
||||
for each failed_tool in issue:
|
||||
SEARCH_TAGS.append(tool_name) # e.g., "get_labels", "validate_repo_org"
|
||||
|
||||
# Add error category
|
||||
SEARCH_TAGS.append(error_category) # e.g., "parameter-format", "authentication"
|
||||
|
||||
# Add component if identifiable
|
||||
if error relates to MCP server:
|
||||
SEARCH_TAGS.append("mcp")
|
||||
if error relates to command:
|
||||
SEARCH_TAGS.append("command")
|
||||
```
|
||||
|
||||
**2. Search lessons learned:**
|
||||
|
||||
```
|
||||
mcp__plugin_projman_gitea__search_lessons(
|
||||
repo=REPO_NAME,
|
||||
tags=SEARCH_TAGS,
|
||||
limit=5
|
||||
)
|
||||
```
|
||||
|
||||
**3. Also search by error keywords:**
|
||||
|
||||
```
|
||||
mcp__plugin_projman_gitea__search_lessons(
|
||||
repo=REPO_NAME,
|
||||
query=[key error message words],
|
||||
limit=5
|
||||
)
|
||||
```
|
||||
|
||||
**4. Display relevant lessons (if any):**
|
||||
|
||||
```
|
||||
Related Lessons Learned
|
||||
=======================
|
||||
|
||||
Found [N] relevant lessons from past fixes:
|
||||
|
||||
📚 Lesson: "Sprint 14 - Parameter validation in MCP tools"
|
||||
Tags: mcp, get_labels, parameter-format
|
||||
Summary: Always validate repo parameter format before API calls
|
||||
Prevention: Add format check at function entry
|
||||
|
||||
📚 Lesson: "Sprint 12 - Graceful fallback for missing config"
|
||||
Tags: configuration, fallback
|
||||
Summary: Commands should work even without .env
|
||||
Prevention: Check for env vars, use sensible defaults
|
||||
|
||||
These lessons may inform your fix approach.
|
||||
```
|
||||
|
||||
If no lessons found, display:
|
||||
```
|
||||
No related lessons found. This may be a new type of issue.
|
||||
```
|
||||
|
||||
### Step 10: Propose Fix Approach
|
||||
|
||||
Based on the analysis, propose a specific fix:
|
||||
@@ -342,7 +410,118 @@ Next Steps:
|
||||
1. Review and merge PR #81
|
||||
2. In test project, pull latest plugin version
|
||||
3. Run /debug-report to verify fix
|
||||
4. If passing, close issue #80
|
||||
4. Come back and run Step 15 to close issue and capture lesson
|
||||
```
|
||||
|
||||
### Step 15: Verify, Close, and Capture Lesson
|
||||
|
||||
**This step runs AFTER the user has verified the fix works.**
|
||||
|
||||
When user returns and confirms the fix is working:
|
||||
|
||||
**1. Close the issue:**
|
||||
|
||||
```
|
||||
mcp__plugin_projman_gitea__update_issue(
|
||||
repo=REPO_NAME,
|
||||
issue_number=ISSUE_NUMBER,
|
||||
state="closed"
|
||||
)
|
||||
```
|
||||
|
||||
**2. Ask about lesson capture:**
|
||||
|
||||
Use AskUserQuestion:
|
||||
|
||||
```
|
||||
This fix addressed [ERROR_TYPE] in [COMPONENT].
|
||||
|
||||
Would you like to capture this as a lesson learned?
|
||||
|
||||
Options:
|
||||
- Yes, capture lesson (helps avoid similar issues in future)
|
||||
- No, skip (trivial fix or already documented)
|
||||
```
|
||||
|
||||
**3. If user chooses Yes, auto-generate lesson content:**
|
||||
|
||||
```
|
||||
LESSON_TITLE = "Sprint [N] - [Brief description of fix]"
|
||||
# Example: "Sprint 17 - MCP parameter validation"
|
||||
|
||||
LESSON_CONTENT = """
|
||||
## Context
|
||||
|
||||
[What was happening when the issue occurred]
|
||||
- Command/tool being used: [FAILED_TOOL]
|
||||
- Error encountered: [ERROR_MESSAGE]
|
||||
|
||||
## Problem
|
||||
|
||||
[Root cause identified during investigation]
|
||||
|
||||
## Solution
|
||||
|
||||
[What was changed to fix it]
|
||||
- Files modified: [LIST]
|
||||
- PR: #[PR_NUMBER]
|
||||
|
||||
## Prevention
|
||||
|
||||
[How to avoid this in the future]
|
||||
|
||||
## Related
|
||||
|
||||
- Issue: #[ISSUE_NUMBER]
|
||||
- PR: #[PR_NUMBER]
|
||||
"""
|
||||
|
||||
LESSON_TAGS = [
|
||||
tool_name, # e.g., "get_labels"
|
||||
error_category, # e.g., "parameter-format"
|
||||
component, # e.g., "mcp", "command"
|
||||
"bug-fix"
|
||||
]
|
||||
```
|
||||
|
||||
**4. Show lesson preview and ask for approval:**
|
||||
|
||||
```
|
||||
Lesson Preview
|
||||
==============
|
||||
|
||||
Title: [LESSON_TITLE]
|
||||
Tags: [LESSON_TAGS]
|
||||
|
||||
Content:
|
||||
[LESSON_CONTENT]
|
||||
|
||||
Save this lesson? (Y/N/Edit)
|
||||
```
|
||||
|
||||
**5. If approved, create the lesson:**
|
||||
|
||||
```
|
||||
mcp__plugin_projman_gitea__create_lesson(
|
||||
repo=REPO_NAME,
|
||||
title=LESSON_TITLE,
|
||||
content=LESSON_CONTENT,
|
||||
tags=LESSON_TAGS,
|
||||
category="sprints"
|
||||
)
|
||||
```
|
||||
|
||||
**6. Report completion:**
|
||||
|
||||
```
|
||||
Issue Closed & Lesson Captured
|
||||
==============================
|
||||
|
||||
Issue #[N]: CLOSED
|
||||
Lesson: "[LESSON_TITLE]" saved to wiki
|
||||
|
||||
This lesson will be surfaced in future /debug-review
|
||||
sessions when similar errors are encountered.
|
||||
```
|
||||
|
||||
## DO NOT
|
||||
@@ -350,8 +529,9 @@ Next Steps:
|
||||
- **DO NOT** skip reading relevant files - this is MANDATORY
|
||||
- **DO NOT** proceed past approval gates without user confirmation
|
||||
- **DO NOT** guess at fixes without evidence from code
|
||||
- **DO NOT** close issues - let user verify fix works first
|
||||
- **DO NOT** close issues until user confirms fix works (Step 15)
|
||||
- **DO NOT** commit directly to development or main branches
|
||||
- **DO NOT** skip the lessons learned search - past fixes inform better solutions
|
||||
|
||||
## If Investigation Finds No Bug
|
||||
|
||||
|
||||
Reference in New Issue
Block a user