Ticket Lifecycle Workflow

Complete workflow from starting a ticket to delivering work.

Prerequisites

CLI installed and authenticated
Access to GitHub workspace

GitHub Issues

Workflow Overview

In GitHub Issues, tickets flow through these statuses:

Backlog - New issues created by anyone. Product maintains the backlog, ordering items so top items are ready to work on.
Ready - Tickets ready to be picked up. Both Product and Engineers can move tickets from Backlog to Ready.
Planning - Engineer is planning the implementation (auto-transitioned when you run wseng start).
In Progress - Active development (auto-transitioned when you save your plan via wseng ws save-plan).
Review - Code is ready for review. PRs are linked via keywords (automatically) or manually in GitHub UI.
Done - Development complete, awaiting product acceptance.
Accepted - Product has accepted the work.

Project Board

All tickets across products and teams are tracked in a single GitHub Project. Tickets created in any of our repositories automatically appear here.

Built-in views:

View	Scope	Description
My Board	Personal	Kanban board of your active tickets
My Backlog	Personal	Your upcoming/unstarted tickets
Completed by me	Personal	Tickets you've finished
Board	Team-wide	All active tickets across the department
Backlog	Team-wide	All upcoming tickets across the department
Completed	Team-wide	All completed tickets across the department

Custom views: Each team or project can create additional views by clicking "Add view" in the project. Filter by labels, assignees, milestones, or any combination to match your workflow.

The Standard Flow

# 1. Start ticket (transitions Backlog/Ready → Planning)
wseng start ws-eng-cli/123
# Or just use issue number if in current repo:
wseng start 123

# 2. Plan implementation
# Edit .context/plan/plan.md with your approach

# 3. Save plan (transitions Planning → In Progress)
wseng ws save-plan

# 4. Make code changes

# 5. Commit
wseng commit

# 6. Generate changelog
wseng changelog

# 7. Record demo
wseng demo

# 8. Move ticket to Review (manual in GitHub UI)

Step 1: Start the Ticket

wseng start ws-eng-cli/123
# Or just the issue number if working in the repo:
wseng start 123

What this does:

Creates branch and pull request
Downloads ticket description to .context/ticket.md
Auto-generates blank plan at .context/plan/plan.md
Transitions ticket from Backlog or Ready to Planning status
Links PR to the issue (via keywords)

Step 2: Write the Plan

Open .context/plan/plan.md and document your implementation approach. Use Cursor or your IDE to explore the codebase and understand requirements from .context/ticket.md.

Good plan structure:

## Files to Create/Modify

- src/services/user.service.ts
- src/resolvers/user.resolver.ts

## Implementation Steps

1. Add getUserProfile method to UserService
2. Expose via GraphQL resolver
3. Add unit tests for service
4. Add E2E test for GraphQL query

Step 3: Save the Plan

wseng ws save-plan

Saves plan to repository and transitions ticket from Planning to In Progress.

Step 4-6: Implement, Commit, Document

Make your changes, then:

# AI-generated commit messages
wseng commit

# Generate summary of changes
wseng changelog

Step 7: Record Demo

wseng demo

Records screen with OBS Studio, uploads to Google Drive, links to ticket/PR. See command reference for OBS setup.

Common Variations

NO-TICKET branches:

wseng start NO-TICKET "quick fix description"

Create new ticket:

wseng start NEW "feature description"

This creates a GitHub Issue in the current repository. The issue is automatically added to the shared GitHub Project, and ticket types/defaults are filled automatically.

Sub-Issues (Subtasks)

GitHub sub-issues are hierarchical - you can create sub-issues of sub-issues up to 8 levels deep, with up to 100 sub-issues per parent. Sub-issues can span repositories (parent and child can be in different repos).

Create sub-issue via CLI:

wseng subtask ws-eng-cli/123 --type backend --start

Create sub-issue via GitHub UI:

Click the "Create sub-issue" button at the bottom of any issue description. You can also add existing issues as sub-issues via the dropdown.

Auto-create sub-issues from plan:

The save-plan command can automatically create sub-issues if you set subtasks: true in the plan frontmatter.

Key differences from old Jira subtasks:

Sub-issues are fully-featured issues (not a limited subtask type)
Hierarchical: sub-issues can have their own sub-issues
Cross-repo: parent and child issues can be in different repositories
Progress tracking: GitHub Projects shows sub-issue completion progress automatically

Ticket ID Format

GitHub Issues use the format repo/number (e.g., ws-eng-cli/123). If you're working in the current repository, you can just use the issue number (e.g., 123). This can be overridden using project-level or repository-level configuration.

Common Pitfalls

❌ Bad: Starting ticket assigned to someone else

wseng start ws-eng-cli/123
# Error: Ticket assigned to another engineer

Solution: Use --force-assignment to override.

❌ Bad: Skipping the plan

Starting to code immediately without writing a plan leaves the ticket in "Planning" status and makes story point calculation inaccurate.

Solution: Always write and save your plan before coding. It forces you to think through the approach.