Skip to content

Writing Issues

Standards and templates for writing clear, actionable YouTrack issues. Every issue should give the assignee enough information to start working without asking clarifying questions.

The minimum viable issue

Every issue, regardless of type, must have:

  1. A clear summary in imperative mood ("Fix pagination in user list", "Add retry logic to upload endpoint", "Shoot custom product set for X")
  2. Enough context to start — what the templates below help you provide
  3. A "done when" signal — acceptance criteria, expected behavior, or deliverable spec

If you're unsure how much detail to add, ask yourself: could someone pick this up tomorrow and start working without messaging me first?

Engineering templates

Bug

Use when something is broken — observed behavior doesn't match expected behavior.

## Observed behavior
What actually happens. Be specific — include error messages, HTTP status codes, UI state.

## Expected behavior
What should happen instead.

## Reproduction steps
1. Go to ...
2. Click ...
3. Observe ...

Environment: [browser/OS/staging/prod]

## Evidence
Screenshots, console logs, network traces, or video if available.

## Severity
- [ ] Blocking workflow (no workaround)
- [ ] Has workaround (describe it)

Tips for bug writers:

  • "It doesn't work" is never enough. What doesn't work, where, and since when?
  • If you can't reproduce it consistently, say so — intermittent bugs are still valid, but flag it.
  • Include the URL, user account, or data that triggers the issue.
  • Screenshots and videos save everyone time. A 10-second screen recording beats a paragraph.

User Story

Use when describing new capability from a user's perspective.

## Story
As a [role/persona], I want [capability], so that [value/outcome].

## Acceptance criteria
- [ ] Criterion 1 (checkable, specific)
- [ ] Criterion 2
- [ ] ...

## Out of scope
- What this explicitly does NOT include

## Design
Link to mockup/wireframe if applicable.

## Notes
Any technical hints, constraints, or context the assignee should know.

Tips for story writers:

  • The "so that" clause matters — it tells the developer why, which helps them make good judgment calls during implementation.
  • Acceptance criteria should be binary: done or not done. Avoid "the page should feel fast" — use "the page loads in under 2 seconds."
  • "Out of scope" prevents creep. If you know someone will ask "should we also do X?", answer it upfront.

Task

Use for prescriptive work — the writer already knows what needs to be done.

## Objective
One sentence: what needs to happen.

## Context
Why this is needed now. What depends on it, what triggered it.

## Requirements
- [ ] Requirement 1
- [ ] Requirement 2
- [ ] ...

## Done when
How to verify this is complete (test command, observable change, etc.)

Tips for task writers:

  • Tasks are instructions, not wishes. "Improve performance" is a goal, not a task. "Add database index on users.email" is a task.
  • If you find yourself writing more than 5 requirements, consider whether this should be an Epic with subtasks.

Epic

Use for goals that decompose into multiple issues across one or more sprints.

## Goal
What we're trying to achieve (1-2 sentences).

## Scope
### In scope
- ...

### Out of scope
- ...

## Success criteria
How we know the epic is done — measurable outcomes.

## Subtasks
Initial breakdown (will evolve):
- [ ] Subtask 1 → [issue link]
- [ ] Subtask 2 → [issue link]
- [ ] ...

Tips for epic writers:

  • An epic is a container, not an issue to assign. Don't put implementation detail here — that goes in subtasks.
  • Each subtask should be independently deliverable. If subtask B can't start until subtask A is merged, note the dependency.
  • Close the epic only when all subtasks are Done.

Production templates

These cover work that flows through the Production State lifecycle (Requirements → Preparation → Execution → Dataset Creation → Review → Delivered).

Shooting Task

Use for custom shoots tracked in YouTrack — non-standard productions that don't fit the in-app kanban workflow.

## Why this is in YouTrack
What makes this shoot non-standard (custom requirements, cross-team coordination, etc.)

## Subject
What's being shot. Product reference, brief description.

## Special requirements
- Equipment, location, talent, styling, or technique needs
- Anything that deviates from standard guidelines

## In-app reference
Link to related in-app guidelines if applicable.

## Output specs
- Format and resolution
- Number of deliverables
- Delivery destination

## Deadline
Target delivery date.

Note

Most shoots are tracked in the in-app kanban system, not YouTrack. Only create a Shooting Task here for productions that need cross-team coordination or have non-standard requirements.

Creative Deliverable

Use for post-production and design work — retouching, compositing, graphic design, brand assets.

## Deliverable
What's being produced (1 sentence).

## Source assets
Link to raw files, shoot task reference, or source material.

## Requirements
- Style/brand guidelines reference
- Specific creative direction or constraints
- Revision rounds expected

## Output specs
- Format and dimensions
- Color profile
- Delivery location (folder, system, handoff)

## Deadline
Target delivery date.

Dataset Creation

Use for data labeling, annotation, quality control, and data pipeline work.

## Objective
What dataset is being created or curated.

## Source data
Description of input data, location, format.

## Criteria
- Labeling/annotation rules
- Quality thresholds (accuracy %, review sample rate)
- Edge case handling

## Volume
Number of items to process.

## Output
- Format and schema
- Destination (storage, pipeline, system)

## Deadline
Target delivery date.

Writing for non-technical contributors

If you're not an engineer, focus on:

  1. Describe the problem or need, not the solution. "Customers can't find their order history" is better than "add a SQL query to the orders table."
  2. Show, don't tell. Screenshots, screen recordings, and links to the exact page/screen are worth more than descriptions.
  3. State the urgency. Is this blocking a client? Is there a deadline? Set the Priority field accordingly.
  4. Don't worry about format. Write what you know. The backlog maintainer will formalize it into the right template during sprint planning.

The two-step process

Not every issue starts polished. We support a capture → formalize workflow:

Step 1: Capture (anyone)

Create the issue with whatever you have. Set the Type, write a summary, dump your context. If it's rough, set the state to Proposal — this signals it needs refinement before it's actionable.

Step 2: Formalize (backlog maintainer)

During sprint planning or backlog grooming, rough issues get shaped into template-conforming format:

  • Rewrite the summary in imperative mood
  • Fill in template sections based on available context
  • Add acceptance criteria or done-when conditions
  • Set Category, Complexity, and Estimation
  • Move from Proposal → Open when ready

Use the /formalize-issue skill in Claude Code to accelerate this step — it reads the rough issue and suggests a template-conforming rewrite.

Quick reference

Type Key question the template answers
Bug "Can I reproduce this?"
User Story "How do I know when I'm done?"
Task "What exactly do I need to do?"
Epic "What's the goal and what's in/out?"
Shooting Task "Why is this here and what's special?"
Creative Deliverable "What am I producing and to what spec?"
Dataset Creation "What are the criteria and volume?"