Ticket Template

Use this template as a starting point for new tickets. Adapt based on complexity:

Simple tickets: Use minimal template (title + brief what/why/how)
Complex features: Use full template with all sections
Bugs: Use bug-specific template (STR + Expected vs Actual)

Simple Ticket Template

Title: [Action] [What] [Where if specific]

[1-2 sentence context about why this matters]

[Brief: what needs to change]

Acceptance Criteria:
- [ ] Criterion 1
- [ ] Criterion 2

Complex Feature Ticket Template

Title: [Action] [What] for [User Type/Context]

## Context
[2-3 sentences explaining why this matters]
- Problem it solves:
- User impact:
- Business value:

## Requirements
- Functional requirement 1
- Functional requirement 2
- Non-functional requirement (performance, compatibility, etc.)
- Integration points with [System X]

## Acceptance Criteria

### Given-When-Then Examples
Given [initial state]
When [action taken]
Then [expected outcome]

### Additional Checkboxes
- [ ] API endpoint returns 200 status
- [ ] Error handling for [edge case] returns 400
- [ ] Documentation updated
- [ ] Test coverage at [X]%

## Open Questions
- [Engineering] How should we handle [technical concern]?
- [Product] What's the expected behavior for [scenario]?
- [Business] Do we need [compliance/security feature]?

## Dependencies
- Depends on: [Ticket ID if applicable]
- Blocks: [Ticket ID if applicable]

## Estimate
[Story points or T-shirt size if using estimation]

Bug Ticket Template

Title: [Bug] [Component] [Symptom]

## Steps to Reproduce
1. Navigate to [page/screen]
2. [Action 1]
3. [Action 2]
4. [Observe result]

## Expected Behavior
[What should happen]

## Actual Behavior
[What is actually happening]

## Environment
- Browser: [Chrome 120 on macOS / etc.]
- Device: [Device model]
- OS: [OS and version]
- Network: [Stable / Flaky / etc.]
- User Type: [Admin / Regular user / etc.]

## Additional Context
[Screenshots, error logs, data samples if helpful]

## Severity
- [ ] Critical (Service down, data loss, security)
- [ ] High (Core feature broken, widespread impact)
- [ ] Medium (Feature partially broken, workaround exists)
- [ ] Low (Minor UI issue, edge case, cosmetic)

## Acceptance Criteria
- [ ] Bug reproduction confirmed
- [ ] Root cause identified and documented
- [ ] Fix implemented and tested
- [ ] Regression test added
- [ ] Verified in [environment]

Epic Ticket Template

Title: [Capability] for [User/Team/Domain]

## Overview
[1-2 sentence description of the epic scope]

## Goals
- Goal 1: [Specific, measurable outcome]
- Goal 2: [Specific, measurable outcome]

## Scope
**In Scope**:
- Feature/capability 1
- Integration with [System X]
- Support for [User type/scenario]

**Out of Scope** (explicitly defer):
- Feature that's related but separate
- Advanced feature deferred to later

## Success Metrics
- [Metric 1]: Target [X] by [Date]
- [Metric 2]: Target [X] by [Date]

## Key Dependencies
- Requires: [System/Feature that must be in place]
- Blocks: [Work that will be blocked on this]
- Integrates with: [Related systems]

## Acceptance Criteria
- [ ] All child tickets completed
- [ ] Documentation complete
- [ ] [User type] can [primary use case]
- [ ] Performance target [X] met
- [ ] Rollout to [X]% of users successful

## Open Questions
- [Product] Should we support [feature variant]?
- [Engineering] Is [architecture choice] the right approach?
- [Design] What's the rollout experience?

## Planned Breakdown (Initial)
- [Ticket category 1]: e.g., Backend API implementation
- [Ticket category 2]: e.g., Frontend UI
- [Ticket category 3]: e.g., Testing and validation
- [Ticket category 4]: e.g., Documentation

Notes on Template Usage

Title Writing Tips:

✅ "Add CSV export for user data"
✅ "[Bug] Email parser fails on UTF-8 domains"
✅ "[Epic] Mobile app for iOS"
❌ "Export feature"
❌ "Parser issue"

When to use Complex Template:

Feature impacts multiple systems
Epic or large feature
Cross-team dependencies
Performance or security considerations
Unclear requirements or assumptions

When to use Simple Template:

UI/text changes
Small bug fixes
Documentation updates
Isolated improvements

Accepting Criteria Tips:

Make them testable without ambiguity
Include both happy path and error cases
For complex logic, use Given-When-Then format
For simple features, checkboxes are fine
Avoid "code is clean" or vague criteria

Content Guidelines

Default: Product-Centric Focus

Tickets should prioritize user value and business outcomes:

✅ Good - Product-focused:

Title: Enable users to export their data

Context:
Users need ability to download their data for backup and compliance purposes.
This supports GDPR requirements and builds user trust.

Requirements:
- Export button accessible from user profile
- Support CSV and JSON formats
- Include all user data except internal system fields

Acceptance Criteria:
- [ ] User can initiate export from profile page
- [ ] System generates file within 30 seconds
- [ ] Downloaded file contains complete user data
- [ ] Format selection (CSV/JSON) works correctly

❌ Poor - Too implementation-heavy:

Title: Add CSV export endpoint

Context:
Need to implement CSV export using fast-csv library.
Code: const csv = require('fast-csv'); function exportData() { ... }

Requirements:
- Create /api/export endpoint
- Use fast-csv for generation
- Return response with proper headers

Including Technical Details

Include technical specifics when:

Explicitly requested:

User: "Create ticket for payment processing. Make sure to note we're using Stripe, not our usual PayPal."

✅ Ticket includes:
Technical Note: Use Stripe payment gateway (deviation from standard PayPal integration)
due to better support for recurring subscriptions.

Convention deviation:

User: "We need to use Redis for this caching layer instead of Memcached"

✅ Ticket includes:
Technical Note: Implement caching with Redis (deviation from Memcached standard)
to support pub/sub for real-time invalidation.

Critical architectural constraint:

✅ Ticket includes:
Technical Constraint: Use event-driven architecture with message queue
to support asynchronous processing and avoid blocking user requests.

What NOT to include:

❌ Avoid:

Code snippets or function implementations
Specific variable names or method signatures
Sample code from conversations or documentation

✅ Instead use:

Architectural patterns: "Use Observer pattern for notifications"
Technology choices: "Implement with WebSockets for bidirectional communication"
Design constraints: "Must support horizontal scaling"

6.7 KiB Raw Permalink Blame History