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:

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

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.

Working with Ticket Fields

Ticket data lives in three places: project custom fields on the right-hand panel, a computed fields comment, and an output comment. Each has different editability and purpose.

Project Custom Fields

All issues across all products and teams share a single GitHub Project (#553). Custom fields are visible and editable from the right-hand panel in GitHub Issues — expand the project section to see them.

Most fields are auto-filled or defaulted by the CLI. Status is the one you'll change manually most often. Date fields like Completed At and Accepted At are auto-set on status transitions but exist as project fields (rather than only in the computed fields comment) so they can be used for sorting and filtering in project views.

Computed Fields Comment

A read-only comment marked with <!-- TICKET_COMPUTED_FIELDS --> that the CLI maintains automatically. It renders as a markdown table:

Do not edit this comment. These fields are recomputed from status transitions, assignee changes, and QC outcomes. They update when you run CLI workflow commands (wseng qc start, wseng qc pass, etc.) or explicitly via wseng tk update-computed-fields.

Output Comment

A comment at the top of the issue marked with <!-- TICKET_OUTPUT_SECTION -->. The CLI creates it automatically when you start a ticket so it stays pinned near the top of the conversation, not buried under activity.

What to put here:

• Testing instructions for reviewers
• Links to deployed environments
• Key implementation notes

Note: demo video links go in the Demo Recording URL project custom field, not here. The Output section is for content that doesn't fit a single URL field — detailed testing steps, multiple environment links, etc.

How to edit: Find the comment with the # Output header on the issue, click the ··· menu → Edit. Keep the HTML marker as the first line:

<!-- TICKET_OUTPUT_SECTION -->
# Output
## Testing Instructions
1. Run `npm test` to verify all tests pass
2. Start dev server: `npm run dev`
3. Navigate to http://localhost:3000/profile
4. Verify the new profile icon appears

CLI automation: Commands like wseng demo and wseng changelog automatically prepend content to this comment with a --- separator. Your manual content is preserved below.

Time Tracking

Time tracking is not managed in GitHub. Previously tracked via Jira custom fields (billed time, etc.), these metrics now live in the Personal Dashboards spreadsheet, which includes delivery metrics, time spent breakdowns, and per-ticket efficiency data.

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.

Related Docs

RCA Workflow

Special workflow for bugs requiring root cause analysis.

Code Review Workflow

What happens during QC and how to address feedback.

Command Reference

Full reference for all commands used in this workflow.