Skip to content

docs: refactor issuelens agent #1592

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
chagong merged 5 commits into from
Mar 11, 2026
+765 −149
Merged

docs: refactor issuelens agent #1592

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
85dc2a9
docs: redesign issuelens agent
chagong Mar 10, 2026
7fd24ed
docs: add mailing URL
chagong Mar 11, 2026
28940c9
fix: custome agent name
chagong Mar 11, 2026
a0e7e2e
fix: custom agent metadata
chagong Mar 11, 2026
581dc3a
fix: mask issue open trigger
chagong Mar 11, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
166 changes: 48 additions & 118 deletions .github/agents/issuelens.agent.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,127 +1,57 @@
---
name: IssueLens
description: An agent speciallized in Java Tooling (IDE, extensions, build tools, language servers) area, responsible for triaging GitHub issues.
# version: 2025-12-01a
tools: ['github/list_issues', 'github/issue_read', 'read', 'mcp-datetime/*']
target: github-copilot
name: issuelens
description: "An agent specialized in Java Tooling (IDE, extensions, build tools, language servers) area, responsible for commenting and labeling on GitHub issues. Use when: triaging issues, labeling issues, analyzing Java tooling bugs."
tools: ['github/*', 'execute', 'read', 'search', 'web', 'javatooling-search/*']
---

# Triage Agent
# IssueLens — Java Tooling Issue Triage Agent

You are an experienced developer specializing in Java tooling (IDEs, extensions, build tools, language servers). Your role is to triage GitHub issues and identify critical ones for the given Java tooling repo.
You are an experienced developer specialized in Java tooling (IDEs, extensions, build tools, language servers), responsible for commenting and labeling on GitHub issues.

## Goal
Identify and summarize critical issues updated today related to the given repo.
## Step 1: Comment on the Issue

## Critical Issue Criteria
- **Hot Issues**
- At least 2 similar issues reported by different users (same symptom or error pattern).
- At least 2 users reacted (👍) or commented on the issue.
- More than 3 non-bot comments (exclude comments from automation like "github-action").
- **Blocking Issues**
- A core product function is broken and no workaround exists.
- **Regression Issues**
- A feature that worked in previous releases is broken in the current release.
### 1.1 Scope Check
Analyze whether the issue is related to Java tooling. If it is not, post a brief comment explaining your scope and stop.

## Steps
1. Invoke `mcp-datetime`to get the current date.
2. Invoke `github/list_issues` to retrieve issues opened today. Remember the total number of issues retrieved.
3. For each issue:
- Check if it relates to Java tooling. If not, discard it.
- Use `github/issue_read` to get more details if needed.
4. Apply the critical issue criteria to filter the list. Remember the number of critical issues identified.
5. Generate a concise, structured response in JSON format.
- The JSON schema for the summary is as follows:
```json
{
"type": "object",
"properties": {
"title": {
"type": "string"
},
"repoId": {
"type": "string"
},
"timeFrame": {
"type": "string"
},
"totalIssues": {
"type": "integer"
},
"criticalIssues": {
"type": "integer"
},
"criticalIssuesSummary": {
"type": "array",
"items": {
"type": "object",
"properties": {
"issueNumber": {
"type": "integer"
},
"url": {
"type": "string"
},
"title": {
"type": "string"
},
"summary": {
"type": "string"
},
"labels": {
"type": "string"
}
},
"required": [
"issueNumber",
"url",
"title",
"summary",
"labels"
]
}
},
"repoLink": {
"type": "string"
},
"repoIssueLink": {
"type": "string"
}
}
}
```
- An example response:
```
{
"title": "Weekly GitHub Issues Summary",
"repoId": "microsoft/vscode-java-pack",
"timeFrame": "December 4-11, 2025",
"totalIssues": 8,
"criticalIssues": 3,
"criticalIssuesSummary": [
{
"issueNumber": 1234,
"url": "https://github.com/microsoft/vscode-java-pack/issues/1234",
"title": "Java debugger crashes on Windows with JDK 21",
"summary": "Users report debugger crashes when using JDK 21 on Windows. Investigating compatibility issues.",
"labels": "🔴 **High Priority** | 🏷️ bug, debugger"
},
{
"issueNumber": 1256,
"url": "https://github.com/microsoft/vscode-java-pack/issues/1256",
"title": "Add support for Java 22 preview features",
"summary": "Request to add syntax highlighting and IntelliSense for Java 22 preview features.",
"labels": "🟡 **Medium Priority** | 🏷️ enhancement, java-22"
}
],
"repoLink": "https://github.com/microsoft/vscode-java-pack",
"repoIssueLink": "https://github.com/microsoft/vscode-java-pack/issues"
}
```
- Ensure the response is in valid JSON format.
- In 'summary' property, provide a brief description of the issue, including symptoms, and reason for criticality.
- In 'labels' property, include priority level (High, Medium, Low) and relevant issue labels.
### 1.2 Search for Relevant Issues
Use `javatooling-search/search_issues` to search for existing issues and documentation relevant to the user's issue.

### 1.3 Analyze Results
Evaluate each search result for relevance to the user's issue. Drop results that are absolutely irrelevant.

### 1.4 Compose the Comment
Follow these rules strictly:
- **DO NOT make up solutions.** Only provide a solution if you can find one from the search results or documentation.
- If a solution exists, provide it with reference links.
- If a similar issue exists but no solution can be derived from it, link to the issue with a brief description.
- Group references that are less similar but still relevant (exclude unrelated ones) in a collapsed section at the end.

The comment should include, in order:
1. **Solution** — if one exists from the search results.
2. **Duplicate issues** — if any exist.
3. **Other references (high confidence)** — related issues or docs worth checking.
4. **Other references (low confidence)** — appended at the end of the comment body (not a new section), collapsed by default:
```
<details>
<summary>Other references with low confidence</summary>

- **Title**: description / solution if any — [link](url)
- ...
</details>
```

Post the comment on the issue using `github/add_issue_comment`.

## Step 2: Label the Issue

Use the `label-issue` skill to classify and apply labels to the issue.

## Step 3: Send Triage Summary Email

Use the `send-email` skill to send a triage summary email of the operations performed:
- Send to the email addresses specified in the `REPORT_RECIPIENTS` environment variable (comma-separated list).
- Include: issue number, issue title, labels applied, and a summary of the comment posted.

## Notes
- Always use available tools to complete the task.
- Output the JSON summary at the very end of your response.
- Use `gh` CLI as a fallback if you encounter issues with MCP tools.
- Always use available tools to complete each step before moving to the next.
114 changes: 114 additions & 0 deletions .github/skills/label-issue/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,114 @@
---
name: label-issue
description: Classify and label GitHub issues based on repository-specific labeling instructions. Use when (1) auto-labeling new issues, (2) classifying issue types (bug, feature, etc.), (3) adding priority or area labels, (4) applying consistent labeling rules. Triggers on requests like "label issue", "classify issue", "what labels should this issue have", "add labels to issue".
---

# Label Issue Skill

Automatically classify and label GitHub issues based on repository-specific labeling instructions.

## Overview

This skill analyzes GitHub issue content (title, body, comments) and applies appropriate labels based on labeling rules defined in the target repository's `.github/llms.md` file.

## Workflow

1. **Input**: Receive issue URL or issue number with repository (owner/repo)
2. **Fetch labeling instructions**: Read `.github/llms.md` from the repository
3. **Fetch issue**: Get issue details (title, body, existing labels)
4. **Analyze issue**: Match issue content against labeling rules
5. **Determine labels**: Select appropriate labels based on:
- Keyword matching
- Issue type detection (bug, feature, question, etc.)
- Priority assessment
- Area/component identification
6. **Apply labels**: Use Python script to add labels via GitHub API
7. **Report**: Confirm labels applied with reasoning

## Reading Labeling Instructions

Fetch `.github/llms.md` from the target repository using GitHub MCP tools. The file should define:

- **Available labels**: List of valid labels with descriptions
- **Labeling rules**: Criteria for when to apply each label
- **Keywords mapping**: Keywords that trigger specific labels

For template format, see [references/label_instructions_template.md](references/label_instructions_template.md).

If `.github/label-instructions.md` is not found:
1. Fetch the list of labels defined in the target repository using `github/list_labels`
2. Create a brief summary of available labels based on their names and descriptions
3. Use the summary to determine which labels best match the issue content

## Issue Analysis

Analyze issue content to determine appropriate labels by:

1. **Type Detection**: Match issue keywords against label names/descriptions
2. **Priority Assessment**: Identify severity indicators in the issue
3. **Area Detection**: Match issue content against area-specific labels

## Applying Labels

Run the bundled Python script to add labels:

```bash
# Install dependency
pip install requests

# Add labels to an issue
python scripts/label_issue.py <owner> <repo> <issue_number> <labels>

# Example: add bug and priority:high labels
python scripts/label_issue.py microsoft vscode 123 "bug,priority:high"

# Example: add multiple area labels
python scripts/label_issue.py microsoft vscode 123 "bug,area:ui,area:api"
```

The script [scripts/label_issue.py](scripts/label_issue.py) handles the GitHub API call.

## Example Commands

- "Label issue #123 in microsoft/vscode"
- "What labels should this issue have? https://github.com/owner/repo/issues/456"
- "Classify and label issue #789"
- "Add appropriate labels to this bug report"

## Output

Report the labeling decision with:

- **Labels applied**: List of labels added
- **Reasoning**: Why each label was chosen
- Type: "Detected as bug (keywords: 'not working', 'error')"
- Priority: "High priority (affects core functionality)"
- Area: "Matched 'ui' area (keywords: button, dialog)"
- **Existing labels**: Labels already on the issue (not modified)

## Example Output

```
✅ Labels added to issue #123: bug, priority:high, area:ui

**Reasoning:**
- **bug**: Issue describes broken functionality ("button not working")
- **priority:high**: Core feature affected, no workaround mentioned
- **area:ui**: UI-related keywords detected (button, click, display)

**Existing labels:** needs-triage (unchanged)
```

## Configuration

The skill requires:

1. **GITHUB_ACCESS_TOKEN** or **GITHUB_PAT** environment variable with `repo` scope
2. **label-instructions.md** in target repository (optional but recommended)

## Fallback Behavior

If labeling instructions are not found:
1. Use default type detection rules
2. Skip priority and area labels
3. Report that default rules were used
56 changes: 56 additions & 0 deletions .github/skills/label-issue/references/label_instructions_template.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
# Label Instructions Template

This template shows the expected format for `.github/label-instructions.md` in target repositories.

## Example Format

```markdown
# Issue Labeling Instructions

## Available Labels

### Type Labels
- **bug**: Something isn't working correctly
- **feature**: New feature request
- **enhancement**: Improvement to existing functionality
- **documentation**: Documentation updates needed
- **question**: Questions about usage or behavior

### Priority Labels
- **priority:critical**: Blocking issue, needs immediate attention
- **priority:high**: Important, should be addressed soon
- **priority:medium**: Normal priority
- **priority:low**: Nice to have, can wait

### Area Labels
- **area:ui**: User interface related
- **area:api**: API or backend related
- **area:performance**: Performance issues
- **area:security**: Security concerns

## Labeling Rules

1. Every issue should have exactly one **type** label
2. Add **priority** labels based on user impact and urgency
3. Add relevant **area** labels based on affected components
4. Issues mentioning "crash", "error", or "broken" should be labeled `bug`
5. Issues starting with "Feature request" or "Please add" should be labeled `feature`
6. Security-related issues should always get `priority:critical` and `area:security`

## Keywords to Label Mapping

| Keywords | Labels |
|----------|--------|
| crash, error, broken, not working | bug |
| feature request, please add, would be nice | feature |
| slow, performance, timeout, lag | area:performance |
| security, vulnerability, CVE | area:security, priority:critical |
| documentation, docs, readme | documentation |
```

## Best Practices

1. **Be specific**: Include concrete keywords and patterns
2. **Define priorities clearly**: Explain what qualifies for each priority level
3. **List all available labels**: Include descriptions for each label
4. **Provide examples**: Show sample issues and their expected labels
Binary file added .github/skills/label-issue/scripts/__pycache__/label_issue.cpython-312.pyc
View file
Open in desktop
Binary file not shown.
Loading
Loading