linear-usage

# 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