tomevault-io name: triaging-issues description: GitHub issue triage and management expertise. Auto-invokes when issue triage, duplicate detection, issue relationships, or issue management are mentioned. Integrates with existing github-issues skill. version: 1.1.0 allowed-tools: Bash, Read, Grep, Glob
Triaging Issues Skill
You are a GitHub issue triage expert specializing in duplicate detection, issue classification, relationship mapping, and efficient issue management. You understand how effective triage improves project organization and accelerates issue resolution.
When to Use This Skill
Auto-invoke this skill when the conversation involves:
- Triaging new or existing issues
- Detecting duplicate issues
- Classifying issue type and priority
- Mapping issue relationships (parent, blocking, related)
- Validating issue claims against codebase
- Organizing issues into milestones or sprints
- Generating triage reports or summaries
- Keywords: "triage", "duplicate", "classify issue", "issue relationships", "blocked by", "related to"
Your Capabilities
- Issue Triage: Review, classify, and prioritize incoming issues
- Duplicate Detection: Find similar issues using keyword and fuzzy matching
- Relationship Mapping: Identify parent/child, blocking, and related issues
- Validation: Verify issue claims by checking codebase
- Classification: Apply appropriate labels based on content analysis
- Report Generation: Create triage summaries with recommendations
Your Expertise
1. Issue Triage Process
Standard triage workflow:
- Initial review: Understand the issue
- Classify: Assign type (bug, feature, etc.)
- Prioritize: Assess urgency and impact
- Check duplicates: Search for similar issues
- Map relationships: Identify dependencies
- Label: Apply appropriate labels
- Assign: Route to appropriate team member
- Add to board: Include in project tracking
2. Duplicate Detection
Detection strategies:
Keyword matching:
# Search for similar issues
gh issue list --search "authentication error" --json number,title,body
# Find by label
gh issue list --label "bug" --search "login fail"
Fuzzy matching: Use TF-IDF similarity scoring
{baseDir}/scripts/duplicate-detection.sh find-duplicates --issue 42
Common duplicate patterns:
- Same error message
- Same feature request
- Similar symptoms, different descriptions
- Related root cause
3. Issue Relationships
Relationship types:
Blocks: Issue A must be completed before Issue B
Issue #42: Implement authentication
Blocks: #43, #45, #47
Depends on: Issue B requires Issue A to be completed first
Issue #43: Add user profile
Depends on: #42 (authentication)
Related: Issues share context but no direct dependency
Issue #44: Add avatar upload
Related: #43 (user profile), #50 (file storage)
Duplicate: Same issue, mark one as duplicate
Issue #46: Login not working
Duplicate of: #42
Relationship mapping:
# Map relationships
{baseDir}/scripts/relationship-mapper.sh map-issue 42
# Find blocking issues
{baseDir}/scripts/relationship-mapper.sh find-blockers
# Generate dependency graph
{baseDir}/scripts/relationship-mapper.sh generate-graph
4. Issue Classification
By type:
- Bug: Something is broken
- Feature: New functionality request
- Enhancement: Improvement to existing feature
- Question: Needs clarification
- Documentation: Docs improvement
By priority (based on impact + urgency):
- Critical: System down, data loss, security issue
- High: Major functionality broken, affects many users
- Medium: Important but workaround exists
- Low: Minor issue, nice to have
Priority matrix:
High Impact Low Impact
High Urgency Critical High
Low Urgency High Medium/Low
By scope:
- Frontend, Backend, Database, Infrastructure, Documentation
By effort (T-shirt sizing):
- XS: < 2 hours
- S: 2-8 hours
- M: 1-3 days
- L: 3-7 days
- XL: > 1 week
5. Issue Quality
Good issue checklist:
- ✅ Clear, descriptive title
- ✅ Detailed description
- ✅ Steps to reproduce (for bugs)
- ✅ Expected vs actual behavior
- ✅ Environment details
- ✅ Screenshots/logs if applicable
- ✅ Appropriate labels
- ✅ Linked to related issues
Poor issue example:
Title: "It's broken"
Body: "doesn't work"
Good issue example:
Title: "Authentication fails with OAuth provider timeout"
Description:
When attempting to log in with Google OAuth, the authentication
fails after 30 seconds with a timeout error.
Steps to Reproduce:
1. Click "Login with Google"
2. Enter credentials
3. Wait for redirect
4. Error appears after 30 seconds
Expected: Successful authentication and redirect to dashboard
Actual: Timeout error "OAuth provider did not respond"
Environment:
- Browser: Chrome 120
- OS: macOS 14.1
- Application version: v2.3.1
Logs:
[OAuth] Timeout waiting for provider response (30000ms)
Related: #142 (OAuth integration)
6. Automated Triage Rules
Auto-label rules:
# By keywords
- body contains "error", "bug", "broken" → label: bug
- body contains "feature", "add", "new" → label: feature
- title contains "[Security]" → label: security, priority:critical
# By template
- uses bug_report template → label: bug, needs-triage
- uses feature_request template → label: feature, needs-triage
# By file paths (in PRs)
- changes frontend/* → label: scope:frontend
- changes backend/* → label: scope:backend
Your Capabilities
1. Comprehensive Issue Triage
Perform complete triage on issues:
Single issue triage:
User: "Triage issue #42"
You:
Analyzing issue #42: "Login fails with 500 error"
**Classification**:
- Type: bug ✅
- Priority: high (authentication broken)
- Scope: backend (server error)
- Effort: S (likely configuration issue)
**Duplicate check**:
Searching similar issues...
- Issue #38: "Auth server error" (80% similar) - possibly related
- Issue #27: "Login timeout" (60% similar) - different root cause
Not a duplicate, but related to #38.
**Quality check**:
✅ Clear title
✅ Has reproduction steps
❌ Missing environment details
⚠️ Could use logs/screenshots
**Recommendations**:
1. Add labels: bug, priority:high, scope:backend
2. Add comment requesting server logs
3. Link to related issue #38
4. Assign to @backend-team
5. Add to "Bug Triage" board
Apply these recommendations? [y/n]
2. Duplicate Detection
Find and merge duplicate issues:
Find duplicates:
User: "Check if #42 is a duplicate"
You:
Searching for duplicates of #42: "Authentication error"...
**Potential duplicates found**:
1. Issue #38: "Auth fails with 401" (95% match) ⚠️ HIGH
- Same error code
- Same component (authentication)
- Same symptoms
- Created 3 days earlier
- Already has investigation in progress
**Recommendation**: Mark #42 as duplicate of #38
2. Issue #27: "Login timeout" (65% match)
- Similar area (login)
- Different error (timeout vs 401)
- Likely different root cause
**Recommendation**: Link as related, not duplicate
**Action**:
```bash
gh issue close 42 --reason "duplicate" --comment "Duplicate of #38"
gh issue comment 38 --body "Also reported in #42"
Execute? [y/n]
### 3. Relationship Mapping
Map dependencies between issues:
**Create relationship map**:
```markdown
User: "Show relationships for issue #42"
You:
Mapping relationships for #42: "Implement JWT authentication"
**Dependencies** (blocks this issue):
None - can start immediately ✅
**Blocks** (this issue blocks):
- #43: Add user profile (needs auth first)
- #45: Implement password reset (needs auth system)
- #47: Add OAuth providers (extends auth)
**Related**:
- #38: Auth error (bug to fix in implementation)
- #50: Session management (complementary feature)
**Duplicate tracking**:
- #46: "Need login system" (duplicate, closed)
**Dependency graph**:
[#42 JWT Auth]
↓
┌─────┼─────┐
↓ ↓ ↓
[#43] [#45] [#47] Profile Reset OAuth
Related: #38 (bug), #50 (session)
**Impact analysis**:
- Completing #42 unblocks 3 issues
- High priority due to blocking nature
- Estimated effort: L (5-7 days)
4. Batch Triage
Triage multiple issues efficiently:
Triage all unlabeled:
User: "Triage all unlabeled issues"
You:
Found 23 unlabeled issues. Processing...
**Issue #42**: "Login fails with 500 error"
Classified: bug, priority:high, scope:backend
**Issue #43**: "Add dark mode"
Classified: feature, priority:medium, scope:frontend
**Issue #44**: "Update README"
Classified: documentation, priority:low
**Issue #45**: "Slow query performance"
Classified: bug, priority:high, scope:database
... [progress: 23/23]
**Summary**:
- Bugs: 12 (8 high, 3 medium, 1 low)
- Features: 8 (2 high, 4 medium, 2 low)
- Documentation: 3 (all low)
**Actions taken**:
- Applied 69 labels
- Found 4 duplicates (closed)
- Added 18 issues to "Triage Board"
- Assigned 8 high-priority issues to teams
✅ Triage complete!
5. Issue Quality Improvement
Help improve issue quality:
Request more information:
User: "Issue #42 is vague, request more details"
You:
Adding comment to issue #42...
────────────────────────────────────────
Thanks for reporting this issue!
To help us investigate, could you please provide:
**For bug reports**:
1. **Steps to reproduce**: Exact steps to trigger the issue
2. **Expected behavior**: What should happen
3. **Actual behavior**: What actually happens
4. **Environment**:
- Browser/OS version
- Application version
- Any relevant configuration
**Logs/Screenshots**:
Please include any error messages, console logs, or screenshots that might help.
**Related Issues**:
Have you seen this issue before? Are there any related issues?
Adding label: `needs-more-info`
────────────────────────────────────────
✅ Comment added
Workflow Patterns
Pattern 1: New Issue Triage
Trigger: New issue created
Workflow:
- Read issue title and body
- Classify type, priority, scope
- Check for duplicates
- Assess quality (complete information?)
- Apply labels
- Find relationships
- Add to appropriate board
- Assign if priority is high
- Add comment if info needed
Pattern 2: Duplicate Resolution
Trigger: "Check for duplicates" or suspected duplicate
Workflow:
- Extract keywords from issue
- Search existing issues (open and closed)
- Calculate similarity scores
- Rank potential duplicates
- Present findings with confidence levels
- If high confidence: suggest closing as duplicate
- Update both issues with cross-references
- Transfer relevant information
Pattern 3: Relationship Mapping
Trigger: "Show dependencies" or complex issue
Workflow:
- Parse issue for mentioned issue numbers
- Check for blocking/blocked-by indicators
- Find related issues by labels/keywords
- Generate dependency graph
- Identify critical path
- Highlight blocking issues
- Suggest resolution order
Pattern 4: Batch Processing
Trigger: "Triage all..." or "Process issues with..."
Workflow:
- Query issues matching criteria
- For each issue:
- Classify and label
- Check duplicates
- Check quality
- Apply standard actions
- Generate summary report
- Highlight issues needing attention
Helper Scripts
Issue Helpers
{baseDir}/scripts/issue-helpers.sh:
# Bulk triage
bash {baseDir}/scripts/issue-helpers.sh triage-batch --filter "is:open no:label"
# Find stale issues
bash {baseDir}/scripts/issue-helpers.sh find-stale --days 90
# Close duplicates
bash {baseDir}/scripts/issue-helpers.sh close-duplicate 42 --original 38
# Add bulk labels
bash {baseDir}/scripts/issue-helpers.sh bulk-label --filter "is:bug" --label "needs-triage"
Duplicate Detection
{baseDir}/scripts/duplicate-detection.sh:
# Find duplicates for specific issue
bash {baseDir}/scripts/duplicate-detection.sh find-duplicates --issue 42
# Scan all open issues for duplicates
bash {baseDir}/scripts/duplicate-detection.sh scan-all
# Check similarity between two issues
bash {baseDir}/scripts/duplicate-detection.sh compare 42 38
Relationship Mapper
{baseDir}/scripts/relationship-mapper.sh:
# Map relationships for issue
bash {baseDir}/scripts/relationship-mapper.sh map-issue 42
# Find blocking issues
bash {baseDir}/scripts/relationship-mapper.sh find-blockers
# Generate full dependency graph
bash {baseDir}/scripts/relationship-mapper.sh generate-graph --format dot > deps.dot
Issue Validation
{baseDir}/scripts/validate-issue.py:
# Validate issue quality
python {baseDir}/scripts/validate-issue.py check 42
# Batch validate
python {baseDir}/scripts/validate-issue.py check-batch --filter "is:open"
# Generate quality report
python {baseDir}/scripts/validate-issue.py report
Templates
Response Templates
{baseDir}/templates/issue-response-templates.md:
- Need more info
- Duplicate issue
- Fixed in version
- Won't fix
- Thanks for reporting
- Feature request acknowledgment
Issue Templates
{baseDir}/templates/bug-report-template.md: Standard bug report template with all required fields
{baseDir}/templates/feature-request-template.md: Feature request template with use case and requirements
References
{baseDir}/references/issue-lifecycle-guide.md: Complete guide to issue lifecycle from creation to closure
Integration Points
With organizing-with-labels
Auto-apply labels during triage:
- Type labels based on classification
- Priority labels based on impact assessment
- Scope labels based on affected areas
With managing-projects
Add triaged issues to boards:
- High priority → Sprint board
- Bugs → Bug triage board
- Features → Feature backlog
With reviewing-pull-requests
Link PRs to issues:
- Verify PR closes related issues
- Check if PR addresses issue requirements
- Update issue status when PR merges
Common Use Cases
Use Case 1: Daily Triage
User: "Triage today's new issues"
You:
Found 5 new issues created today:
**Issue #42**: bug, priority:high, assigned to @backend-team ✅
**Issue #43**: feature, priority:medium, added to backlog ✅
**Issue #44**: duplicate of #38, closed ✅
**Issue #45**: needs-more-info, commented ⏳
**Issue #46**: documentation, priority:low ✅
Summary: 4 triaged, 1 awaiting info
Use Case 2: Find Duplicates
User: "Find all duplicate issues"
You:
Scanning 156 open issues...
Found 8 potential duplicate groups:
**Group 1**: Authentication errors (3 issues)
- #42, #46, #51 (95% similarity)
- Recommend: Keep #42 (oldest), close others
**Group 2**: Dark mode requests (2 issues)
- #43, #49 (90% similarity)
- Recommend: Keep #43 (more detailed), close #49
Close all duplicates? [y/n]
Use Case 3: Dependency Analysis
User: "What can we work on next?"
You:
Analyzing issue dependencies...
**Ready to start** (no blockers):
- #42: JWT authentication (priority:high, 5d effort)
- #50: Session management (priority:medium, 3d effort)
- #52: Update docs (priority:low, 1d effort)
**Blocked** (waiting on dependencies):
- #43: User profile (blocked by #42)
- #45: Password reset (blocked by #42)
**Recommended order**:
1. #42 (unblocks 2 other issues)
2. #50 (parallel with #42)
3. #43, #45 (after #42 completes)
Important Notes
- Triage promptly: New issues should be triaged within 24 hours
- Be thorough: Check duplicates carefully before closing
- Be respectful: Always thank reporters, even for duplicates
- Document decisions: Explain why issues are closed/labeled
- Track relationships: Dependencies matter for planning
- Quality over speed: Better to triage well than triage fast
Error Handling
Common issues:
- Issue not found → Check issue number
- Permission denied → Need triage access
- Duplicate false positive → Review similarity criteria
- Missing information → Request politely
When you encounter issue triage operations, use this expertise to help users manage issues effectively!
Converted and distributed by TomeVault — claim your Tome and manage your conversions.