Create Ticket Skill

When creating a ticket, follow this structured process. A good ticket gives the assignee everything they need to understand, implement, and verify the work without back-and-forth questions.

1. Classify the Ticket Type

Determine what kind of ticket this is:

Type	When	Icon
Bug	Something is broken or behaving incorrectly	🐛
Feature	New functionality or capability	✨
Improvement	Enhancing existing functionality	💡
Tech Debt	Refactoring, cleanup, or infrastructure improvement	🔧
Security	Vulnerability fix or security hardening	🔒
Performance	Speed, memory, or scalability improvement	⚡
Documentation	Missing or outdated docs	📝
Infrastructure	CI/CD, deployment, monitoring, DevOps	🏗️
Design	UI/UX changes, visual updates	🎨
Research / Spike	Investigation before implementation	🔍
Test	Adding or fixing tests	✅
Dependency	Library updates, version bumps	📦

2. Gather Context

Before writing the ticket, gather relevant information:

For Bugs

# Check recent commits that might be related
git log --oneline -20

# Check for related error handling
grep -rn "catch\|throw\|Error\|Exception" --include="*.ts" --include="*.js" --include="*.py" src/ | grep -i "[relevant keyword]"

# Check related files
find src -name "*[relevant keyword]*" -type f

# Check for existing related issues
gh issue list --search "[keyword]" --state all 2>/dev/null

For Features

# Check if any related code or patterns exist
grep -rn "[related pattern]" --include="*.ts" --include="*.js" --include="*.py" src/

# Check existing models/services that would be affected
find src -name "*[related area]*" -type f

# Check for related tickets already filed
gh issue list --search "[keyword]" --state all 2>/dev/null

3. Ticket Templates

🐛 Bug Report

## Title
[Component/Area]: [Clear description of the bug]

Examples:
- "Auth: Users get logged out after password change on other devices"
- "Checkout: Duplicate charges when clicking Pay button twice quickly"
- "Search: Results return 0 items for queries containing special characters"

## Type
Bug

## Priority
[Critical / High / Medium / Low]

## Description

### What Happens
[Describe the actual behavior — what the user sees or experiences]

### What Should Happen
[Describe the expected behavior — what the correct outcome should be]

### Steps to Reproduce
1. [First step — be specific about starting state]
2. [Second step — include exact inputs, clicks, actions]
3. [Third step — include any timing or sequence requirements]
4. **Observe**: [What goes wrong]

### Reproduction Rate
[Always / Intermittent (~X% of the time) / Only under specific conditions]

### Environment
- **Browser/Client**: [Chrome 120, Safari 17, iOS app v3.2, etc.]
- **OS**: [macOS 14.2, Windows 11, iOS 17, Android 14]
- **Environment**: [Production / Staging / Local]
- **User role**: [Admin / Editor / Viewer]
- **Account**: [test-user@example.com or account ID if relevant]

### Error Details
[Include any of the following if available:]
- Error message (exact text)
- Console errors
- Network request/response (status code, body)
- Stack trace
- Log entries
- Screenshot or recording

### Impact
- **Users affected**: [All users / Specific group / Edge case]
- **Severity**: [Data loss / Broken feature / Degraded experience / Visual only]
- **Workaround available**: [Yes — describe / No]
- **Revenue impact**: [Yes — describe / No / Unknown]

### Root Cause (if known)
[If you've investigated and have a hypothesis, include it here]

### Suggested Fix (if known)
[If you have an idea of how to fix it, describe the approach]

## Acceptance Criteria
- [ ] Bug no longer occurs when following the reproduction steps
- [ ] Existing related tests still pass
- [ ] New test added covering this specific scenario
- [ ] Fix doesn't introduce regressions in [related area]
- [ ] [Any specific verification criteria]

## Related
- Related to: #[issue-number]
- Introduced in: [commit/PR if known]
- Affected files: [list key files if known]

## Labels
bug, [component], [priority]

✨ Feature Request

## Title
[Area]: [Clear description of the feature]

Examples:
- "Auth: Add SSO login via SAML for enterprise customers"
- "Dashboard: Add date range filter to analytics charts"
- "API: Add bulk create endpoint for products"

## Type
Feature

## Priority
[Critical / High / Medium / Low]

## Description

### User Story
As a [role/persona],
I want to [action/capability],
so that [benefit/value].

### Background / Context
[Why is this feature needed? What problem does it solve?
Link to customer feedback, support tickets, or product brief.]

### Detailed Requirements

#### Functional Requirements
1. [Specific requirement — what the system must do]
2. [Specific requirement]
3. [Specific requirement]

#### Non-Functional Requirements
- **Performance**: [Response time, throughput expectations]
- **Scale**: [Expected data volume, concurrent users]
- **Security**: [Auth requirements, data sensitivity]
- **Accessibility**: [WCAG level, screen reader support]
- **Internationalization**: [Languages, locales, RTL support]

### User Flow
1. User navigates to [page/section]
2. User clicks [element]
3. System displays [response]
4. User enters [input]
5. System processes and shows [result]

### UI/UX
[Link to Figma/design mockups if available]

[If no designs yet, describe the expected interface:]
- Where does this feature appear in the UI?
- What does the user see?
- What interactions are available?
- What feedback does the user get?

### API Changes (if applicable)

#### New Endpoints

POST /api/v1/[resource] Request: { field1: string, field2: number } Response: 201 { id: string, field1: string, field2: number, createdAt: string }

#### Modified Endpoints

GET /api/v1/[resource] New query params: ?dateFrom=ISO&dateTo=ISO

### Database Changes (if applicable)
- New table: `[table_name]` with columns: [list]
- Modified table: `[table_name]` — add column: [column] ([type])
- New index: `[index_name]` on [table].[columns]

### Notifications / Emails (if applicable)
- When: [trigger condition]
- To: [recipient]
- Channel: [email / push / in-app / SMS]
- Content: [brief description]

### Configuration (if applicable)
- New env var: `[VAR_NAME]` — [purpose]
- New feature flag: `[flag_name]` — [purpose]
- New admin setting: [description]

## Acceptance Criteria
- [ ] [Specific, testable criterion — "User can ___"]
- [ ] [Specific, testable criterion]
- [ ] [Specific, testable criterion]
- [ ] [Edge case handled — "System handles ___ by ___"]
- [ ] [Error case handled — "When ___ fails, user sees ___"]
- [ ] [Performance criterion — "Response time under ___ms"]
- [ ] Unit tests added for new business logic
- [ ] Integration tests added for new endpoints
- [ ] Documentation updated
- [ ] Feature flag controls rollout (if applicable)

## Out of Scope
[Explicitly list what this ticket does NOT include.
This prevents scope creep and sets clear boundaries.]
- Not including [related but separate feature]
- Not supporting [specific edge case — future ticket]
- Not changing [related area that stays as-is]

## Dependencies
- Blocked by: #[issue-number] — [why]
- Depends on: [external service / team / decision]
- Blocks: #[issue-number] — [why]

## Design / Technical Approach (optional)
[If the approach has been discussed or decided, document it here.
Include alternatives considered and why this approach was chosen.]

### Option A: [Approach name]
- Pros: ...
- Cons: ...

### Option B: [Approach name] ✅ Recommended
- Pros: ...
- Cons: ...

## Subtasks
- [ ] [Subtask 1 — e.g., "Create database migration"]
- [ ] [Subtask 2 — e.g., "Implement API endpoint"]
- [ ] [Subtask 3 — e.g., "Build UI component"]
- [ ] [Subtask 4 — e.g., "Add tests"]
- [ ] [Subtask 5 — e.g., "Update documentation"]

## Estimation
- **Size**: [XS / S / M / L / XL] or [Story Points: 1/2/3/5/8/13]
- **Estimated time**: [X hours / X days]
- **Complexity**: [Low / Medium / High]
- **Risk**: [Low / Medium / High — describe risk factors]

## Related
- Product brief: [link]
- Design: [Figma link]
- Customer request: [support ticket / feedback link]
- Related tickets: #[number], #[number]

## Labels
feature, [component], [priority], [team]

💡 Improvement

## Title
[Area]: [Clear description of the improvement]

Examples:
- "Checkout: Add address autocomplete to reduce form abandonment"
- "Dashboard: Show loading skeletons instead of spinners"
- "Email: Add unsubscribe link to marketing emails"

## Type
Improvement

## Priority
[Critical / High / Medium / Low]

## Description

### Current Behavior
[How the feature works today]

### Proposed Improvement
[How it should work after this change]

### Motivation
[Why is this improvement needed? Metrics, user feedback, or observations that support it.]
- User feedback: [quote or link]
- Metric: [current value → target value]
- Competitive: [what competitors do]

### Impact
- **Users affected**: [who benefits]
- **Expected outcome**: [metric improvement, reduced friction, etc.]

## Acceptance Criteria
- [ ] [Specific, measurable criterion]
- [ ] [Specific, measurable criterion]
- [ ] Existing functionality not degraded
- [ ] Tests updated to cover the improvement

## Subtasks
- [ ] [Subtask 1]
- [ ] [Subtask 2]
- [ ] [Subtask 3]

## Estimation
- **Size**: [XS / S / M / L / XL]
- **Complexity**: [Low / Medium / High]

## Labels
improvement, [component], [priority]

🔧 Tech Debt

## Title
[Area]: [Clear description of the tech debt]

Examples:
- "Auth: Refactor UserService into separate AuthService and ProfileService"
- "API: Replace manual validation with Zod schemas across all endpoints"
- "Tests: Fix flaky order integration tests caused by race conditions"

## Type
Tech Debt

## Priority
[Critical / High / Medium / Low]

## Description

### Current State
[Describe the current problematic code/architecture]
- What's wrong with it?
- Where in the codebase? [file paths]
- How long has it been this way?

### Problems It Causes
[Why does this matter? Be specific about the pain.]
- Slows down development: [how]
- Causes bugs: [which ones]
- Makes onboarding harder: [how]
- Increases risk: [what risk]
- Performance impact: [what impact]

### Proposed Solution
[Describe the target state]
- What should the code look like after?
- What pattern/approach should replace the current one?
- What files will be affected?

### Migration Strategy
[How to get from current state to target state]
1. [Step 1]
2. [Step 2]
3. [Step 3]

### Risk Assessment
- **Behavior changes**: [None / Minimal — describe / Significant — describe]
- **Regression risk**: [Low / Medium / High — describe]
- **Rollback plan**: [How to revert if something goes wrong]

## Acceptance Criteria
- [ ] Code follows the new pattern/structure
- [ ] All existing tests pass without modification (behavior preserved)
- [ ] No new warnings or linting errors
- [ ] Performance not degraded (benchmark if applicable)
- [ ] [Specific structural criterion]

## Subtasks
- [ ] [Subtask 1]
- [ ] [Subtask 2]
- [ ] [Subtask 3]

## Estimation
- **Size**: [XS / S / M / L / XL]
- **Complexity**: [Low / Medium / High]
- **Risk**: [Low / Medium / High]

## Labels
tech-debt, refactor, [component], [priority]

🔒 Security

## Title
[Security]: [Clear description of the vulnerability or hardening]

Examples:
- "Security: Fix XSS vulnerability in user profile rendering"
- "Security: Add rate limiting to authentication endpoints"
- "Security: Rotate exposed API key in commit history"

## Type
Security

## Priority
[Critical / High / Medium / Low]

## ⚠️ Sensitivity
[Is this ticket sensitive? Should it be private/confidential?]
- If actively exploitable: Make ticket PRIVATE
- If theoretical/hardening: Can be public

## Description

### Vulnerability (if applicable)
- **Type**: [XSS / SQL Injection / IDOR / CSRF / etc.]
- **CWE**: [CWE-XXX if known]
- **CVSS Score**: [if assessed]
- **Affected component**: [file path / endpoint]
- **Exploitability**: [Easy / Moderate / Difficult / Theoretical]

### Current Risk
[What could an attacker do with this vulnerability?]

### Proposed Fix
[How to remediate]

### Discovery
[How was this found? Security audit, penetration test, dependency scan, etc.]

## Acceptance Criteria
- [ ] Vulnerability is remediated
- [ ] Regression test added for the specific attack vector
- [ ] Security audit passes on the affected area
- [ ] No new vulnerabilities introduced by the fix
- [ ] Incident response completed (if applicable)

## Labels
security, [severity], [component]

⚡ Performance

## Title
[Perf]: [Clear description of the performance issue]

Examples:
- "Perf: Reduce /api/products response time from 2.3s to <500ms"
- "Perf: Fix N+1 query in order listing page"
- "Perf: Reduce initial bundle size from 1.8MB to under 500KB"

## Type
Performance

## Priority
[Critical / High / Medium / Low]

## Description

### Current Performance
- **Metric**: [Response time / Load time / Memory usage / Bundle size]
- **Current value**: [measured value with tool used]
- **Target value**: [acceptable threshold]
- **Affected area**: [endpoint / page / operation]

### Root Cause (if known)
[What's causing the slowness?]

### Proposed Solution
[How to improve performance]

### Measurement Plan
- **Tool**: [Lighthouse / Chrome DevTools / APM / custom benchmark]
- **Baseline**: [current measurement]
- **Target**: [goal measurement]
- **How to verify**: [specific steps to measure after fix]

## Acceptance Criteria
- [ ] [Metric] improved from [current] to [target]
- [ ] No functionality regression
- [ ] Performance test added to prevent future regression
- [ ] Measured in production-like environment

## Labels
performance, [component], [priority]

🔍 Research / Spike

## Title
[Spike]: [Clear description of what needs investigation]

Examples:
- "Spike: Evaluate real-time notification options (WebSocket vs SSE vs polling)"
- "Spike: Investigate feasibility of migrating from REST to GraphQL"
- "Spike: Research GDPR compliance requirements for user data export"

## Type
Research / Spike

## Priority
[High / Medium / Low]

## Description

### Question to Answer
[The specific question(s) this spike should answer]

1. [Question 1]
2. [Question 2]
3. [Question 3]

### Context
[Why do we need this research? What decision depends on it?]

### Scope
[What should be investigated and what's out of scope]

### Time Box
[Maximum time to spend: e.g., 2 days, 4 hours, 1 sprint]

## Expected Deliverables
- [ ] Written summary of findings
- [ ] Pros/cons comparison of options (if applicable)
- [ ] Recommendation with reasoning
- [ ] Proof of concept (if applicable)
- [ ] Estimated effort for implementation
- [ ] Follow-up tickets created based on findings

## Labels
spike, research, [component]

🏗️ Infrastructure

## Title
[Infra]: [Clear description of the infrastructure change]

Examples:
- "Infra: Set up staging environment with automated deployments"
- "Infra: Add Datadog APM monitoring to production services"
- "Infra: Migrate database from RDS t3.medium to r6g.large"

## Type
Infrastructure

## Priority
[Critical / High / Medium / Low]

## Description

### Current State
[Current infrastructure setup for the affected area]

### Desired State
[Target infrastructure setup]

### Changes Required
1. [Change 1]
2. [Change 2]
3. [Change 3]

### Impact
- **Downtime required**: [Yes — estimated duration / No]
- **Cost change**: [+$X/month / -$X/month / Neutral]
- **Services affected**: [list]
- **Rollback plan**: [how to revert]

## Acceptance Criteria
- [ ] [Infrastructure change verified]
- [ ] Monitoring/alerting configured
- [ ] Documentation updated
- [ ] Team notified of changes
- [ ] Runbook updated (if applicable)

## Labels
infrastructure, devops, [priority]

4. Estimation Guide

Size Estimation

Size	Story Points	Time Estimate	Characteristics
XS	1	< 2 hours	Config change, copy update, one-line fix
S	2	2-4 hours	Simple bug fix, small component, add test
M	3-5	1-2 days	New feature within existing patterns, moderate refactor
L	8	3-5 days	Complex feature, new patterns, multiple components
XL	13	1-2 weeks	Large feature, architectural change, cross-team work
XXL	21+	2+ weeks	Should be broken into smaller tickets

Complexity Factors

• Low: Follows existing patterns, well-understood area, minimal dependencies
• Medium: Some new patterns needed, touches 2-3 modules, moderate testing effort
• High: New architecture, cross-team dependencies, unfamiliar territory, high risk

Signals That a Ticket Is Too Big

• More than 5 subtasks
• Estimated at L or larger
• Touches more than 3 unrelated areas
• Requires multiple reviewers from different teams
• Can't be described in a single user story
• Estimated at more than 1 week

If too big: Break it into smaller tickets and create an epic to group them.

5. Priority Framework

Priority	Criteria	Response
🔴 Critical	Production down, data loss, security breach, revenue blocking	Fix immediately, drop everything
🟠 High	Major feature broken, significant user impact, approaching deadline	Fix this sprint
🟡 Medium	Minor feature issue, workaround exists, improvement with clear value	Schedule for next sprint
🟢 Low	Cosmetic, nice-to-have, minor tech debt, edge case	Add to backlog, address when convenient

6. Auto-Generate Subtasks

Based on the ticket type and scope, generate appropriate subtasks:

Feature Subtasks Pattern

- [ ] Design: Create/review UI mockups
- [ ] DB: Create migration for [new table/columns]
- [ ] API: Implement [endpoint(s)]
- [ ] Service: Implement business logic in [service]
- [ ] UI: Build [component(s)]
- [ ] Tests: Add unit tests for [service/component]
- [ ] Tests: Add integration tests for [endpoint(s)]
- [ ] Docs: Update API documentation
- [ ] Docs: Update README / user docs
- [ ] Review: Code review and QA

Bug Fix Subtasks Pattern

- [ ] Investigate: Reproduce and identify root cause
- [ ] Fix: Implement the fix in [file(s)]
- [ ] Test: Add regression test for this specific scenario
- [ ] Test: Verify fix in staging environment
- [ ] Verify: Confirm related features not affected

Tech Debt Subtasks Pattern

- [ ] Analyze: Map current code and dependencies
- [ ] Plan: Document migration strategy
- [ ] Implement: Refactor [component/module] (phase 1)
- [ ] Implement: Refactor [component/module] (phase 2)
- [ ] Test: Verify behavior is preserved
- [ ] Cleanup: Remove deprecated code
- [ ] Docs: Update architecture documentation

7. Platform-Specific Issue Creation

GitHub Issues

# Create issue
gh issue create \
  --title "feat(auth): Add OAuth2 login with Google and GitHub" \
  --body "$(cat ticket.md)" \
  --label "feature,auth,size/M" \
  --assignee "@me" \
  --milestone "v2.4.0"

# Create with project board
gh issue create \
  --title "fix(checkout): Prevent duplicate charges on retry" \
  --body "$(cat ticket.md)" \
  --label "bug,critical,checkout" \
  --project "Sprint 24"

GitLab Issues

# Create issue
glab issue create \
  --title "feat(auth): Add OAuth2 login with Google and GitHub" \
  --description "$(cat ticket.md)" \
  --label "feature,auth" \
  --assignee "@me" \
  --milestone "v2.4.0"

Jira (via API)

# Create via Jira REST API
curl -X POST "https://your-domain.atlassian.net/rest/api/3/issue" \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic $(echo -n email:api-token | base64)" \
  -d '{
    "fields": {
      "project": { "key": "PROJ" },
      "summary": "feat(auth): Add OAuth2 login with Google and GitHub",
      "description": { "type": "doc", "version": 1, "content": [...] },
      "issuetype": { "name": "Story" },
      "priority": { "name": "High" },
      "labels": ["feature", "auth"],
      "story_points": 5
    }
  }'

Linear (via API)

# Create via Linear API
curl -X POST "https://api.linear.app/graphql" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $LINEAR_API_KEY" \
  -d '{
    "query": "mutation { issueCreate(input: { title: \"...\", description: \"...\", teamId: \"...\", priority: 2 }) { success issue { id identifier url } } }"
  }'

8. Quality Checklist

Before finalizing any ticket, verify:

### Ticket Quality Check
- [ ] **Title is clear** — someone can understand the scope from the title alone
- [ ] **Type is correct** — bug vs feature vs tech debt etc.
- [ ] **Priority is justified** — based on impact and urgency, not gut feeling
- [ ] **Description is complete** — no critical information missing
- [ ] **Acceptance criteria are testable** — each one can be verified as done/not done
- [ ] **Scope is bounded** — out of scope is explicitly stated
- [ ] **Dependencies are listed** — blockers and related work identified
- [ ] **Estimation is reasonable** — sized appropriately, broken down if too large
- [ ] **Labels are applied** — type, component, priority, size
- [ ] **Assignee or team is clear** — someone knows this is theirs
- [ ] **No jargon without explanation** — a new team member could understand this
- [ ] **Subtasks are actionable** — each subtask can be independently worked on

Output Format

Present the ticket as:

1. Ticket Preview

Show the complete formatted ticket ready to be filed.

2. Metadata Summary

Type: Feature
Priority: High
Size: M (3-5 story points, ~2 days)
Complexity: Medium
Labels: feature, auth, size/M
Subtasks: 6
Dependencies: None

3. Filing Options

• Command to create on GitHub/GitLab/Jira
• Or the formatted markdown ready to paste

4. Related Tickets (if applicable)

• Suggest related tickets that should also be created
• Identify if this should be part of an epic

Adaptation Rules

• Detect project tracker — check for .github/, .gitlab-ci.yml, or ask the user
• Match existing ticket style — look at recent issues to match team conventions
• Detect from conversation — if the user describes a bug casually, extract the structured information
• Detect from code — if pointed at a file or error, analyze the code to fill in technical details
• Break down large scope — if the request is too big for one ticket, suggest an epic with multiple tickets
• Ask only what's missing — if the user provides most details, don't ask for information you can infer
• Security sensitivity — if it's a vulnerability, recommend making the ticket private
• Suggest priority — based on impact analysis, suggest a priority with reasoning

Summary

End every ticket creation with:

1. Ticket ready — formatted and ready to file
2. Filing command — platform-specific command to create it
3. Suggested assignee — based on code ownership if detectable
4. Related work — other tickets that should be created alongside this one
5. Questions — anything that needs clarification before filing