mattmre/triage-issue-skill

Triage Issue Skill

Analyze a GitHub issue, verify claims against the codebase, and close invalid issues with a technical response.

Trigger

User provides a GitHub issue URL or number, e.g.:

• /triage-issue 1970
• /triage-issue https://github.com/adenhq/hive/issues/1970

Workflow

Step 1: Fetch Issue Details

gh issue view <number> --repo adenhq/hive --json title,body,state,labels,author

Extract:

• Title
• Body (the claim/bug report)
• Current state
• Labels
• Author

If issue is already closed, inform user and stop.

Step 2: Analyze the Claim

Read the issue body and identify:

1. The core claim - What is the user asserting?
2. Technical specifics - File paths, function names, code snippets mentioned
3. Expected behavior - What do they think should happen?
4. Severity claimed - Security issue? Bug? Feature request?

Step 3: Investigate the Codebase

For each technical claim:

1. Find the referenced code using Grep/Glob/Read
2. Understand the actual implementation
3. Check if the claim accurately describes the behavior
4. Look for related tests, documentation, or design decisions

Step 4: Evaluate Validity

Categorize the issue as one of:

| Category | Action | |----------|--------| | Valid Bug | Do NOT close. Inform user this is a real issue. | | Valid Feature Request | Do NOT close. Suggest labeling appropriately. | | Misunderstanding | Prepare technical explanation for why behavior is correct. | | Fundamentally Flawed | Prepare critique explaining the technical impossibility or design rationale. | | Duplicate | Find the original issue and prepare duplicate notice. | | Incomplete | Prepare request for more information. |

Step 5: Draft Response

For issues to be closed, draft a response that:

1. Acknowledges the concern - Don't be dismissive
2. Explains the actual behavior - With code references
3. Provides technical rationale - Why it works this way
4. References industry standards - If applicable
5. Offers alternatives - If there's a better approach for the user

Use this template:

## Analysis

[Brief summary of what was investigated]

## Technical Details

[Explanation with code references]

## Why This Is Working As Designed

[Rationale]

## Recommendation

[What the user should do instead, if applicable]

---
*This issue was reviewed and closed by the maintainers.*

Step 6: User Review

Present the draft to the user with:

## Issue #<number>: <title>

**Claim:** <summary of claim>

**Finding:** <valid/invalid/misunderstanding/etc>

**Draft Response:**
<the markdown response>

---
Do you want me to post this comment and close the issue?

Use AskUserQuestion with options:

• "Post and close" - Post comment, close issue
• "Edit response" - Let user modify the response
• "Skip" - Don't take action

Step 7: Execute Action

If user approves:

# Post comment
gh issue comment <number> --repo adenhq/hive --body "<response>"

# Close issue
gh issue close <number> --repo adenhq/hive --reason "not planned"

Report success with link to the issue.

Important Guidelines

1. Never close valid issues - If there's any merit to the claim, don't close it
2. Be respectful - The reporter took time to file the issue
3. Be technical - Provide code references and evidence
4. Be educational - Help them understand, don't just dismiss
5. Check twice - Make sure you understand the code before declaring something invalid
6. Consider edge cases - Maybe their environment reveals a real issue

Example Critiques

Security Misunderstanding

"The claim that secrets are exposed in plaintext misunderstands the encryption architecture. While SecretStr is used for logging protection, actual encryption is provided by Fernet (AES-128-CBC) at the storage layer. The code path is: serialize → encrypt → write. Only encrypted bytes touch disk."

Impossible Request

"The requested feature would require [X] which violates [fundamental constraint]. This is not a limitation of our implementation but a fundamental property of [technology/protocol]."

Already Handled

"This scenario is already handled by [code reference]. The reporter may be using an older version or misconfigured environment."