/triage-issue

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