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

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

markdown
## 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:

bash
# 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."