182 lines
3.8 KiB
Markdown
182 lines
3.8 KiB
Markdown
---
|
|
name: linear-usage
|
|
description: This skill should be used when user asks about "Linear issues", "issue tracking best practices", "sprint planning", "Linear project management", or "creating Linear issues".
|
|
---
|
|
|
|
# Linear & Issue Tracking Best Practices
|
|
|
|
## Issue Writing Guidelines
|
|
|
|
### Clear Titles
|
|
|
|
Write titles that describe the problem or outcome:
|
|
|
|
- **Good:** "Users can't reset password on mobile Safari"
|
|
- **Bad:** "Password bug"
|
|
- **Good:** "Add export to CSV for user reports"
|
|
- **Bad:** "Export feature"
|
|
|
|
### Effective Descriptions
|
|
|
|
Include:
|
|
|
|
1. **Context:** Why this matters
|
|
2. **Current behavior:** What happens now (for bugs)
|
|
3. **Expected behavior:** What should happen
|
|
4. **Steps to reproduce:** For bugs
|
|
5. **Acceptance criteria:** Definition of done
|
|
|
|
### Templates
|
|
|
|
**Bug report:**
|
|
|
|
```
|
|
## Description
|
|
Brief description of the issue.
|
|
|
|
## Steps to Reproduce
|
|
1. Step one
|
|
2. Step two
|
|
3. Issue occurs
|
|
|
|
## Expected Behavior
|
|
What should happen.
|
|
|
|
## Actual Behavior
|
|
What happens instead.
|
|
|
|
## Environment
|
|
- Browser/OS
|
|
- User type
|
|
```
|
|
|
|
**Feature request:**
|
|
|
|
```
|
|
## Problem Statement
|
|
What problem does this solve?
|
|
|
|
## Proposed Solution
|
|
High-level approach.
|
|
|
|
## Acceptance Criteria
|
|
- [ ] Criterion 1
|
|
- [ ] Criterion 2
|
|
```
|
|
|
|
## Label Taxonomy
|
|
|
|
### Recommended Labels
|
|
|
|
**Type labels:**
|
|
|
|
- `bug` - Something isn't working
|
|
- `feature` - New functionality
|
|
- `improvement` - Enhancement to existing feature
|
|
- `chore` - Maintenance, refactoring
|
|
|
|
**Area labels:**
|
|
|
|
- `frontend`, `backend`, `api`, `mobile`
|
|
- Or by feature area: `auth`, `payments`, `onboarding`
|
|
|
|
**Status labels (if not using workflow states):**
|
|
|
|
- `needs-triage`, `blocked`, `needs-design`
|
|
|
|
### Label Best Practices
|
|
|
|
- Keep label count manageable (15-25 total)
|
|
- Use consistent naming convention
|
|
- Color-code by category
|
|
- Review and prune quarterly
|
|
|
|
## Priority and Estimation
|
|
|
|
### Priority Levels
|
|
|
|
- **Urgent (P0):** Production down, security issue
|
|
- **High (P1):** Major functionality broken, key deadline
|
|
- **Medium (P2):** Important but not urgent
|
|
- **Low (P3):** Nice to have, minor improvements
|
|
|
|
### Estimation Tips
|
|
|
|
- Use relative sizing (points) not hours
|
|
- Estimate complexity, not time
|
|
- Include testing and review time
|
|
- Re-estimate if scope changes significantly
|
|
|
|
## Cycle/Sprint Planning
|
|
|
|
### Cycle Best Practices
|
|
|
|
- **Duration:** 1-2 weeks typically
|
|
- **Capacity:** Plan for 70-80% to allow for interrupts
|
|
- **Carryover:** Review why items didn't complete
|
|
- **Retrospective:** Brief review at cycle end
|
|
|
|
### Planning Process
|
|
|
|
1. Review backlog priorities
|
|
2. Pull issues into cycle
|
|
3. Break down large items (>5 points)
|
|
4. Assign owners
|
|
5. Identify dependencies and blockers
|
|
|
|
## Project Organization
|
|
|
|
### Projects vs Initiatives
|
|
|
|
**Projects:** Focused, time-bound work (1-3 months)
|
|
|
|
- Single team typically
|
|
- Clear deliverable
|
|
- Example: "Mobile app v2 launch"
|
|
|
|
**Initiatives:** Strategic themes
|
|
|
|
- May span multiple projects
|
|
- Longer-term goals
|
|
- Example: "Platform reliability"
|
|
|
|
### Roadmap Tips
|
|
|
|
- Keep roadmap items high-level
|
|
- Update status regularly
|
|
- Link to detailed issues/projects
|
|
- Share with stakeholders
|
|
|
|
## Triage Workflows
|
|
|
|
### Triage Process
|
|
|
|
1. **Review new issues daily**
|
|
2. **Add missing information** (labels, priority)
|
|
3. **Assign to appropriate team/person**
|
|
4. **Link related issues**
|
|
5. **Move to backlog or close if invalid**
|
|
|
|
### Closing Issues
|
|
|
|
Close with clear reason:
|
|
|
|
- **Completed:** Work is done
|
|
- **Duplicate:** Link to original
|
|
- **Won't fix:** Explain why
|
|
- **Invalid:** Missing info, not reproducible
|
|
|
|
## GitHub Integration
|
|
|
|
### Linking PRs to Issues
|
|
|
|
- Reference Linear issue ID in PR title or description
|
|
- Linear auto-links and updates status
|
|
- Use branch names with issue ID for automatic linking
|
|
|
|
### Workflow Automation
|
|
|
|
- PR opened → Issue moves to "In Progress"
|
|
- PR merged → Issue moves to "Done"
|
|
- Configure in Linear settings
|