Workflow

Step 1: Gather Requirements

Ask the user for:

• Team: Which team should own this?
• Type: One of the conventional commit types:
  • feat — New feature or capability
  • fix — Bug fix
  • chore — Maintenance, dependencies, config
  • docs — Documentation changes
  • refactor — Code restructuring without behavior change
  • test — Adding or updating tests
  • ci — CI/CD pipeline changes
  • perf — Performance improvement
  • style — Code style, formatting, linting
• Title: Brief, actionable description (imperative mood preferred)
• Priority: Urgent, High, Normal, or Low?
• Labels: Optional. e.g. frontend, backend, design, devops, tech-debt, customer-request
• Description: What needs to be done? Include:
  • Context/background
  • Acceptance criteria
  • Steps to reproduce (for fix types)
  • Expected vs actual behavior (for fix types)
  • Technical notes (optional)

Step 2: Draft the Ticket

Create a well-structured Linear issue. Use the base template and add type-specific sections as needed.

Base template (all types):

## Summary
Brief overview of what needs to be done.

## Context
Why is this needed? What problem does it solve?

## Acceptance Criteria
- [ ] Criterion 1
- [ ] Criterion 2
- [ ] Criterion 3

## Technical Notes
Any implementation details, gotchas, or suggestions.

## Related
- Links to related issues, PRs, or documentation

Additional sections for fix types — insert between Context and Acceptance Criteria:

## Steps to Reproduce
1. Step 1
2. Step 2
3. Observe the issue

## Expected Behavior
What should happen.

## Actual Behavior
What happens instead.

Step 3: Review & Refine

Before creating the ticket:

• Title is clear, actionable, and uses conventional commit prefix
• Description has enough context for someone unfamiliar with the issue
• Acceptance criteria are specific and testable
• Priority reflects actual urgency
• Labels are appropriate (if provided)
• Type-specific sections are included (e.g. repro steps for fix)

Step 4: Create in Linear

Use the linear_save_issue tool to create the issue. Pass the following parameters:

• title — The drafted title
• description — The full markdown description
• teamId — The team identifier
• priority — Numeric value: 1=Urgent, 2=High, 3=Normal, 4=Low
• labelIds — Array of label identifiers (if applicable)

Always ask the user for confirmation before calling the tool.

Best Practices

Title Formatting

• Use imperative mood: "Add" not "Adding" or "Added"
• Be specific: "fix(auth): resolve 500 error on Safari iOS" not "fix: fix bug"
• Keep it under 80 characters when possible
• Use conventional commit prefix with optional scope: type(scope): description
  • Examples: feat(dashboard): add export to CSV, fix(auth): resolve OAuth token refresh

Description Structure

• Context first: Why does this matter?
• Clear requirements: What exactly needs to happen?
• Acceptance criteria: How do we know it's done?
• Visual aids: Screenshots, diagrams, or mocks when helpful

Priority Guidelines

• Urgent: Production down, security incident, blocking critical path
• High: Significant user impact, blocking other work, near deadline
• Normal: Standard feature work, routine improvements
• Low: Nice-to-have, backlog items, technical debt

Examples

Example: fix

Title: "fix(auth): resolve 500 error on Safari iOS login"

Description:

## Summary
Users cannot log in on Safari iOS — receiving 500 error instead of dashboard.

## Context
Reported by 5+ users in the last 24 hours. Affecting iOS 17+ specifically.

## Steps to Reproduce
1. Open app in Safari on iOS
2. Enter valid credentials
3. Click "Sign In"
4. Observe 500 error page

## Expected Behavior
User should be redirected to dashboard after successful login.

## Actual Behavior
Server returns 500 error, user sees error page.

## Acceptance Criteria
- [ ] Identify root cause of 500 error on iOS Safari
- [ ] Implement fix with cross-browser testing
- [ ] Deploy to production
- [ ] Monitor error rates for 24 hours

## Technical Notes
- May be related to recent cookie changes in PR #234
- Check Safari's handling of SameSite cookies

Example: feat

Title: "feat(settings): add dark mode toggle"

Description:

## Summary
Allow users to switch between light and dark themes in their account settings.

## Context
Top customer request (47 upvotes). Users working at night prefer dark mode for reduced eye strain.

## Acceptance Criteria
- [ ] Add theme toggle in Settings > Appearance
- [ ] Persist theme preference to user account
- [ ] Apply theme immediately without page reload
- [ ] Respect system preference as default
- [ ] Test on all supported browsers

## Technical Notes
- Use CSS custom properties for easy theming
- Store preference in localStorage as fallback
- Consider adding to onboarding flow later

Notes

• Always ask for confirmation before creating tickets
• Suggest improvements to the draft before finalizing
• Offer to create multiple related tickets if needed
• Remind about related work that might need updating (docs, tests, etc.)