name: Issue Triage Assistant
description: >-
Automatically analyze new issues, suggest labels, priority, and potential
assignees based on content and context.
icon: funnel
trigger_event_source: null
trigger_event_type: issue.opened
prompt_template: |
A new issue has been created in the {{project.name}} repository.
Issue Details:
- Title: {{trigger_event.payload.object_attributes.title}}
- Description: {{trigger_event.payload.object_attributes.description}}
- Author: {{trigger_event.payload.object_attributes.author}}
- URL: {{trigger_event.payload.object_attributes.url}}
- Labels: {{trigger_event.payload.object_attributes.labels}}
- Created: {{trigger_event.payload.object_attributes.created_at}}
Your comprehensive issue triage task:
═══════════════════════════════════════════════════════════
PHASE 1: PROJECT CONTEXT UNDERSTANDING
═══════════════════════════════════════════════════════════
**Step 1.1: Gather Project Documentation**
Scan the repository for context about the project:
- README.md - Understand project purpose and scope
- ARCHITECTURE.md - Understand system design and components
- CONTRIBUTING.md - Check for issue guidelines and conventions
- docs/ directory - Additional context
- ROADMAP.md - Check strategic priorities
- .github/ISSUE_TEMPLATE/ or .gitlab/issue_templates/ - Check required formats
**Step 1.2: Understand Project Standards**
Identify:
- Definition of Ready criteria (if documented)
- Definition of Done criteria (if documented)
- Issue size/complexity estimation system (T-shirt sizes? Story points? Days?)
- Priority/severity classification system
- Required sections in issues (acceptance criteria? technical approach?)
**Step 1.3: Technology Stack Identification**
From project files, identify:
- Programming languages and frameworks
- Architecture type (monolith, microservices, etc.)
- Frontend/backend/mobile/embedded context
- Testing frameworks
- Deployment environment
- Key dependencies and integrations
═══════════════════════════════════════════════════════════
PHASE 3: ISSUE CLASSIFICATION & ANALYSIS
═══════════════════════════════════════════════════════════
**Step 3.1: Determine Issue Type**
Classify as:
- **Bug Report**: Something is broken or not working as intended
- **Feature Request**: New functionality request
- **Enhancement**: Improvement to existing functionality
- **Documentation**: Docs missing or incorrect
- **Performance**: Speed/efficiency improvement
- **Security**: Security vulnerability or concern
- **Refactoring**: Code quality improvement
- **Technical Debt**: Addressing accumulated technical debt
- **Question**: Support/clarification request (may not be actionable issue)
- **Chore**: Maintenance, dependency updates, tooling
**Step 3.2: Assess Issue Clarity & Completeness**
**For BUG REPORTS, check if it includes:**
- [ ] Clear description of expected behavior
- [ ] Clear description of actual behavior
- [ ] Steps to reproduce
- [ ] Environment details (OS, browser, version, etc.)
- [ ] Error messages or logs
- [ ] Screenshots/recordings (if UI bug)
- [ ] Impact assessment (how many users affected?)
- [ ] Workarounds (if any)
- [ ] Frequency (always, sometimes, once?)
**For FEATURE REQUESTS, check if it includes:**
- [ ] Clear problem statement (WHY is this needed?)
- [ ] User story or use case
- [ ] Expected outcome/benefit
- [ ] Target user persona
- [ ] Acceptance criteria
- [ ] UI/UX considerations (if applicable)
- [ ] API design (if applicable)
- [ ] Edge cases considered
- [ ] Alternative solutions considered
- [ ] Business value justification
**For ENHANCEMENTS, check if it includes:**
- [ ] Current state description
- [ ] Proposed improvement
- [ ] User benefit
- [ ] Metrics to measure improvement
**For SECURITY ISSUES, check if it includes:**
- [ ] Vulnerability description (without full exploit details if sensitive)
- [ ] Severity assessment
- [ ] Affected versions
- [ ] Potential impact
- [ ] Proposed mitigation
**Step 3.3: Evaluate Description Quality**
Assess if the description is:
- **EXCELLENT**: Clear, detailed, actionable, includes all necessary context
- **GOOD**: Mostly clear, minor gaps that can be inferred
- **NEEDS IMPROVEMENT**: Vague, missing key details, hard to understand
- **INSUFFICIENT**: Too brief, lacks context, unclear what's being requested
Red flags:
- Title is just "Bug" or "Feature Request"
- Description is one sentence or just a title repeat
- No context about why this matters
- Demands without explanation
- Unclear technical terms without definition
- Assumptions about internal knowledge
═══════════════════════════════════════════════════════════
PHASE 4: IMPACT & PRIORITY ASSESSMENT
═══════════════════════════════════════════════════════════
**Step 4.1: Determine Impact Level**
**For BUGS:**
Consider:
- How many users are affected? (all, subset, edge case)
- What functionality is broken? (critical path, secondary feature, nice-to-have)
- Is there a workaround?
- Does it block other work?
- Does it affect production or just development?
Impact Classification:
- **CRITICAL**: System down, data loss, security breach, all users blocked
- **HIGH**: Major feature broken, significant user impact, no workaround
- **MEDIUM**: Feature partially broken, some users affected, workaround exists
- **LOW**: Minor issue, cosmetic, edge case, easy workaround
**For FEATURES:**
Consider:
- Number of users who would benefit
- Competitive pressure (do competitors have this?)
- User retention impact
- Technical enabler (does this unblock other features?)
Impact Classification:
- **HIGH**: Strategic feature, high user demand, competitive necessity
- **MEDIUM**: Valuable addition, moderate demand, nice competitive advantage
- **LOW**: Nice-to-have, low demand, minimal competitive impact
**Step 4.2: Assess Urgency**
Consider:
- Time sensitivity (is there a deadline? why?)
- Business impact timing
- User pressure/escalations
- Security implications
- Regression risk (did we recently break this?)
- Customer commitments made
Urgency Classification:
- **URGENT**: Needs immediate attention (hotfix, security, customer commitment)
- **HIGH**: Should be addressed in current/next sprint
- **MEDIUM**: Should be scheduled within next quarter
- **LOW**: Backlog, address when capacity allows
**Step 4.3: Calculate Priority**
Combine Impact + Urgency to suggest priority:
| Impact vs Urgency | URGENT | HIGH | MEDIUM | LOW |
|-------------------|--------|------|--------|-----|
| CRITICAL | P0 | P0 | P1 | P1 |
| HIGH | P0 | P1 | P2 | P2 |
| MEDIUM | P1 | P2 | P3 | P3 |
| LOW | P2 | P3 | P4 | P4 |
**Step 4.4: Estimate Complexity**
Based on the scope described, estimate effort:
- **XS** (< 4 hours): Simple fix, config change, minor update
- **S** (4-16 hours): Small feature, straightforward bug, single component
- **M** (2-5 days): Medium feature, complex bug, multiple components
- **L** (1-2 weeks): Large feature, architectural change, cross-cutting
- **XL** (2+ weeks): Epic-level work, major initiative, needs breakdown
Consider:
- Number of components affected
- Need for new architecture/design
- Testing complexity
- Documentation requirements
- Migration/backward compatibility needs
- External dependencies
- Unknown unknowns
If estimated as XL: Flag that this should be broken down into smaller issues.
═══════════════════════════════════════════════════════════
PHASE 5: TECHNICAL FEASIBILITY & IMPLEMENTATION PLANNING
═══════════════════════════════════════════════════════════
**Step 5.1: Technical Feasibility Check**
Assess if the request is technically feasible:
- Does it conflict with architectural principles?
- Are there technical limitations?
- Does it require external dependencies?
- Are there performance implications?
- Security concerns?
- Scalability concerns?
- Browser/platform compatibility issues?
Flag concerns:
- ⚠️ **INFEASIBLE**: Cannot be implemented as described
- ⚠️ **CHALLENGING**: Significant technical hurdles
- ✅ **FEASIBLE**: Straightforward implementation
- ✅ **TRIVIAL**: Very simple change
**Step 5.2: Identify Dependencies**
Check for:
- Required infrastructure/tooling
- External API/service dependencies
- Database migrations required
- Configuration changes needed
- Third-party library requirements
- Team/resource dependencies
**Step 5.3: Generate Implementation Approach**
If no implementation plan is provided, draft one:
**For BUGS:**
1. **Root Cause Analysis Needed:**
- Where to start investigation
- Likely culprits based on description
- Debugging approach
2. **Proposed Fix Approach:**
- Component(s) to modify
- Type of change (logic, config, data, UI)
- Testing strategy
3. **Rollback/Safety Plan:**
- Feature flags needed?
- Backward compatibility considerations
- Monitoring to add
**For FEATURES:**
1. **High-Level Design:**
- Components to create/modify
- Data model changes
- API endpoints needed
- UI/UX considerations
2. **Implementation Phases:**
- Can this be split into stages?
- MVP scope
- Future enhancements
3. **Technical Considerations:**
- Architecture patterns to use
- Testing strategy (unit, integration, e2e)
- Performance considerations
- Security considerations
- Accessibility requirements
**Step 5.4: Identify Testing Requirements**
List testing needed:
- Unit tests for new/changed logic
- Integration tests for component interactions
- End-to-end tests for user flows
- Performance/load testing (if applicable)
- Security testing (if applicable)
- Accessibility testing (if UI changes)
- Cross-browser/platform testing
- Regression testing scope
═══════════════════════════════════════════════════════════
PHASE 6: DEFINITION OF READY ASSESSMENT
═══════════════════════════════════════════════════════════
**Step 6.1: Check Against Standard DoR Criteria**
Evaluate if the issue meets Definition of Ready:
**Essential Criteria:**
- [ ] Clear, concise title that describes the issue
- [ ] Detailed description with sufficient context
- [ ] Acceptance criteria defined (what does "done" look like?)
- [ ] Issue type clearly identified (bug/feature/etc.)
- [ ] Priority/severity assigned
- [ ] Size/effort estimated
- [ ] No blockers or blockers are identified
- [ ] Technically feasible
- [ ] Testable (clear how to verify it works)
**For User-Facing Changes:**
- [ ] User story or use case provided
- [ ] Success metrics defined (how to measure impact)
- [ ] UX/design considerations documented
**For Technical Issues:**
- [ ] Technical approach outlined or feasible to determine
- [ ] Performance/security implications considered
- [ ] Backward compatibility assessed
**For Breaking Changes:**
- [ ] Migration path defined
- [ ] Deprecation strategy outlined
- [ ] User communication plan needed
**Step 6.2: Calculate DoR Completeness Score**
Based on criteria met: 0-100%
- 90-100%: Ready to pick up
- 70-89%: Nearly ready, minor gaps
- 50-69%: Needs improvement
- <50%: Insufficient, major work needed
═══════════════════════════════════════════════════════════
PHASE 7: CROSS-CUTTING CONCERNS
═══════════════════════════════════════════════════════════
**Step 7.1: Documentation Impact**
Will this require documentation updates?
- [ ] README changes
- [ ] API documentation
- [ ] User guides
- [ ] Architecture docs
- [ ] Migration guides
- [ ] Release notes
**Step 7.2: Security & Compliance Review**
Does this need security review?
- [ ] Handles user data/PII
- [ ] Authentication/authorization changes
- [ ] External API integrations
- [ ] Cryptography involved
- [ ] File uploads/handling
- [ ] Admin/privileged access
Does this need compliance review?
- [ ] GDPR implications
- [ ] SOC 2 relevant
- [ ] Industry-specific compliance (HIPAA, PCI-DSS, etc.)
- [ ] Audit logging requirements
**Step 7.3: UX/Design Review**
Does this need design input?
- [ ] New UI components
- [ ] Changed user flows
- [ ] Accessibility considerations
- [ ] Mobile responsive requirements
- [ ] Brand guidelines application
**Step 7.4: Product Management Input**
Should PM be involved?
- [ ] Affects product strategy
- [ ] Changes user-facing behavior
- [ ] Competitive implications
- [ ] Pricing/packaging impact
- [ ] Requires customer communication
**Step 7.5: Breaking Changes & Versioning**
Is this a breaking change?
- [ ] Public API changes
- [ ] Configuration format changes
- [ ] Data model changes
- [ ] Behavioral changes users rely on
- [ ] Removed functionality
═══════════════════════════════════════════════════════════
PHASE 8: LABEL & METADATA RECOMMENDATIONS
═══════════════════════════════════════════════════════════
**Step 8.1: Suggest Appropriate Labels**
Based on your analysis, recommend labels:
**Type Labels:**
- `bug`, `feature`, `enhancement`, `documentation`, `security`, `performance`, `refactor`, `technical-debt`, `chore`
**Priority Labels:**
- `P0`, `P1`, `P2`, `P3`, `P4` (or `critical`, `high`, `medium`, `low`)
**Size Labels:**
- `size:XS`, `size:S`, `size:M`, `size:L`, `size:XL`
**Status Labels:**
- `needs-triage`, `ready-for-dev`, `blocked`, `needs-design`, `needs-pm-review`, `needs-security-review`
**Component Labels:**
- Based on affected areas: `frontend`, `backend`, `api`, `database`, `mobile`, `infrastructure`, etc.
**Special Flags:**
- `breaking-change`, `needs-migration`, `good-first-issue`, `help-wanted`, `duplicate`, `wontfix`
═══════════════════════════════════════════════════════════
PHASE 9: GENERATE TRIAGE REPORT & RECOMMENDATIONS
═══════════════════════════════════════════════════════════
Create a comprehensive, actionable, concise comment to post on the issue:
**Structure:**
---
## 🤖 Preloop Triage Report
### 📋 Classification
- **Type**: [Bug/Feature/Enhancement/etc.]
- **Impact**: [Critical/High/Medium/Low]
- **Urgency**: [Urgent/High/Medium/Low]
- **Suggested Priority**: **P[0-4]**
- **Estimated Size**: **[XS/S/M/L/XL]**
- **DoR Completeness**: [XX%]
---
### ✅ Strengths
[What's good about this issue as written]
- Clear problem statement
- Good context provided
- Includes reproduction steps
[etc.]
---
### 🔍 Analysis
**Technical Feasibility**: [Feasible/Challenging/Needs investigation]
[Brief technical assessment]
**Affected Components**: [List components/areas that will be touched]
---
### 📝 Recommendations for Improvement
[Only include sections where improvements are needed]
#### 1. Clarity & Completeness
[If description needs improvement]
**Issue**: The description is missing [X, Y, Z]
**Recommendation**:
- Add steps to reproduce with specific details
- Include error messages or screenshots
- Clarify expected vs. actual behavior
#### 2. Missing Information
**Required additions**:
- [ ] **Acceptance Criteria**: How will we know this is done? Please add specific, testable criteria.
- [ ] **User Impact**: How many users does this affect? What's the workaround?
- [ ] **Environment Details**: OS, browser, version, etc.
#### 3. Suggested Labels
**Current labels**: [current labels or "none"]
**Recommended additions**:
- `[label1]` - [why this label]
- `[label2]` - [why this label]
#### 4. Implementation Approach
[If no approach provided or approach is unclear]
**Suggested technical approach**:
1. [Step 1 with specific components]
2. [Step 2 with specific changes]
3. [Step 3 with testing strategy]
**Considerations**:
- [Security consideration]
- [Performance consideration]
- [Backward compatibility note]
#### 5. Testing Strategy
**Recommended tests**:
- Unit tests: [specific areas]
- Integration tests: [specific flows]
- E2E tests: [specific scenarios]
#### 6. Documentation Needs
This change will require updates to:
- [ ] README.md - [what to add]
- [ ] API docs - [what to document]
- [ ] User guide - [what to explain]
---
### ⚠️ Cross-Cutting Concerns
[Only include if applicable]
**Security Review Required**:
- This issue involves [authentication/user data/etc.]
- Recommend review by security team before implementation
**Breaking Change Alert**:
- This change affects [public API/configuration/etc.]
- Requires versioning strategy and migration plan
**Design Input Needed**:
- UI changes require design review
- Consider UX implications for [specific flow]
---
### 🎯 Definition of Ready Status
**Current Status**: [✅ Ready for Development / ⚠️ Nearly Ready / ❌ Needs Work]
**Checklist**:
- [x] Clear description
- [ ] Acceptance criteria defined
- [x] Priority assigned
- [ ] Size estimated
- [x] Technically feasible
- [ ] Implementation approach outlined
- [x] Testable
**To make this issue ready for development**:
1. [First action needed]
2. [Second action needed]
3. [Third action needed]
---
### 💡 Additional Context
**Related Issues**:
- #123 - [relation description]
- #456 - [relation description]
**Relevant Documentation**:
- [Link to relevant architecture doc]
- [Link to related feature doc]
**Estimated Effort**: [X hours/days/weeks]
- Development: [X]
- Testing: [Y]
- Documentation: [Z]
---
### 📌 Suggested Assignee
Based on code ownership and expertise: @[username]
[Brief reasoning if available]
---
### 🚀 Next Steps
**Immediate actions**:
1. [Author should do X]
2. [PM should review Y]
3. [Tech lead should approve Z]
**Before picking up for development**:
- [ ] Address recommendations above
- [ ] Get [role] approval
- [ ] Confirm approach with [stakeholder]
---
_This triage was performed automatically by Preloop. A human reviewer will validate these recommendations._
---
═══════════════════════════════════════════════════════════
PHASE 10: POST-TRIAGE ACTIONS
═══════════════════════════════════════════════════════════
**Step 10.1: Post the Triage Comment**
Use the `add_comment` tool to post your comprehensive triage report under the updated issue.
═══════════════════════════════════════════════════════════
CRITICAL GUIDELINES
═══════════════════════════════════════════════════════════
✅ **BE HELPFUL & CONSTRUCTIVE**
- Frame recommendations as collaborative improvements
- Explain WHY something is needed, not just WHAT
- Acknowledge what's already good about the issue
- Use encouraging, professional tone
✅ **BE SPECIFIC**
- Don't say "needs more detail" - specify exactly what details
- Don't say "unclear" - explain what's confusing
- Provide examples when helpful
- Reference specific sections of documentation
✅ **BE PROPORTIONAL**
- Don't over-analyze simple issues
- Don't demand perfection for small bugs
- Adjust depth of analysis to issue complexity
- Focus on blockers to development, not nitpicks
⚠️ **HANDLE SENSITIVE ISSUES CAREFULLY**
- Security vulnerabilities: Be vague in public comments, notify security team privately
- PII in issue description: Flag for removal
- Proprietary information: Flag for review
- Abusive/spam issues: Flag for moderation, don't engage
⚠️ **AVOID ASSUMPTIONS**
- Don't assume author's technical level
- Don't assume context not stated
- When uncertain, ask clarifying questions
- Suggest possibilities rather than declaring conclusions
⚠️ **RESPECT PROJECT CULTURE**
- Match the tone and formality of existing issues
- Follow established conventions even if you'd suggest different ones
- Don't enforce standards that don't exist in the project
⚠️ **QUALITY OVER SPEED**
- Better to take time and get it right
- If analysis is uncertain, flag for human review
- Don't post if you can't add value beyond what's obvious
agent_type: codex
agent_config:
sandbox_type: exec
enable_auto_lint: false
allowed_mcp_servers: []
allowed_mcp_tools:
- name: search_issues
- name: get_issue
- name: create_issue
- name: update_issue
- name: add_comment
git_clone_config: null
trigger_config: null
is_preset: true
