Skip to content

Issue Lifecycle & Workflows

How issues move through states, how sprints work, and patterns for organizing work.

State machine

stateDiagram-v2
    [*] --> Open
    Open --> InProgress : Start work
    Open --> Duplicate : Duplicate found
    Open --> Proposal : Needs approval
    InProgress --> Review : Ready for review
    InProgress --> Open : Blocked / paused
    Review --> Done : Approved
    Review --> InProgress : Changes requested
    Proposal --> Open : Approved
    Proposal --> Done : Rejected
    Done --> [*]
    Duplicate --> [*]
    Done --> Invoice : Billable work
    Invoice --> [*]

    InProgress : In Progress

State descriptions

State Meaning
Open Ready to be picked up — backlog or sprint-planned
In Progress Actively being worked on
Review Work complete, awaiting review (code review, QA, or stakeholder sign-off)
Done Accepted and closed
Duplicate Closed as duplicate of another issue
Proposal Idea or request that needs approval before becoming actionable
Invoice Completed billable work pending invoicing

Sprint workflow

All four projects share a unified sprint board. One sprint runs across SAR, IDQ, OPS, and LAB simultaneously.

Sprint naming convention: descriptive name reflecting the sprint goal (e.g. "Customer Shooting Guidelines").

Sprint cycle

  1. Planning — issues are estimated, prioritized, and assigned to the sprint
  2. Execution — developers pick up Open issues, move them through states
  3. Review — completed work is reviewed before the sprint closes
  4. Retrospective — unfinished issues carry over to the next sprint

Epic + subtask patterns

When to use Epics

  • Work that spans 3+ issues or multiple sprints
  • Features that need to be broken down for parallel work
  • Cross-project initiatives (e.g. an Epic in SAR with subtasks in IDQ and OPS)

How to structure

  1. Create the Epic with a clear summary of the goal
  2. Add subtasks (User Stories or Tasks) as children
  3. Each subtask should be independently deliverable
  4. Close the Epic only when all subtasks are Done

Issue summary conventions

Write summaries in imperative mood with a specific scope:

Good Bad
Add retry logic to image upload endpoint Image upload changes
Fix pagination offset in user listing API Bug in API
Create IAM roles for staging environment DevOps stuff

Developer workflow

The typical cycle using CLI tools:

  1. Pick an issue — find an Open issue assigned to you in the current sprint
  2. Start task — sq-dev:start-task creates a branch from the issue
  3. Work — commit regularly with issue ID in commit messages
  4. Close task — sq-dev:close-task squash-merges into dev, updates issue state to Done

See Skills for the full skill reference, or the YouTrack Guide for command bar syntax.