Create Ticket

Purpose

This skill provides step-by-step instructions for creating a new ticket with proper schema validation. Tickets are YAML files stored in

.ushabti/tickets/

that capture ideas for future work.

Prerequisites

Before creating a ticket, invoke the

find-next-ticket-number

skill to determine the next ticket ID.

Required Fields

Every ticket MUST include these fields:

• id: Sequential ticket ID in TNNNN format (e.g., T0001)
• title: Short, descriptive title (used to generate filename slug)
• created: ISO 8601 date in YYYY-MM-DD format (today's date)
• priority: Must be exactly one of:

  low

  ,

  medium

  ,

  high

• context: Multi-line string explaining why this ticket exists
• proposed_work: Multi-line string describing what should be done

Filename Format

Ticket filenames follow the pattern:

TNNNN-short-description.yaml

• TNNNN

  : The ticket ID (zero-padded 4 digits)

• short-description

  : Lowercase, hyphenated slug derived from the title
  • Convert title to lowercase
  • Replace spaces with hyphens
  • Remove special characters except hyphens
  • Limit to ~5 words for brevity

Example: Title "Improve error messages" becomes

T0042-improve-error-messages.yaml

Creation Procedure

Step 1: Determine Next ID

Use the

find-next-ticket-number

skill to get the next ticket ID.

Step 2: Gather Information

Collect the required information:

• Title (brief, descriptive)
• Priority (low, medium, or high)
• Context (why does this ticket exist?)
• Proposed work (what should be done?)

Step 3: Validate Priority

Ensure priority is exactly one of:

low

,

medium

,

high

(all lowercase).

If priority is not valid, stop and report the error.

Step 4: Generate Filename

Convert the title to a slug:

• Lowercase all characters
• Replace spaces with hyphens
• Remove special characters (keep letters, numbers, hyphens)
• Limit to approximately 5 words

Combine with ticket ID:

TNNNN-slug.yaml

Step 5: Create YAML Content

Construct the YAML file with all required fields:

id: T0042
title: Improve error messages
created: 2026-02-01
priority: medium
context: |
  Current error messages are vague and don't help users understand
  what went wrong or how to fix issues. This makes debugging difficult
  and reduces the usability of Ushabti.
proposed_work: |
  - Audit all error messages across agents
  - Replace vague messages with specific, actionable guidance
  - Add error codes for programmatic error handling
  - Update documentation with common errors and solutions

Step 6: Ensure Directory Exists

Ensure the ticket directory exists by running:

mkdir -p .ushabti/tickets

This is idempotent and handles cases where bootstrap or onboarding didn't create the directory.

Step 7: Write File

Write the YAML content to

.ushabti/tickets/TNNNN-slug.yaml

Step 8: Verify

Confirm the file was written successfully and is valid YAML.

Validation Checklist

Before considering the ticket created, verify:

• File exists in

  .ushabti/tickets/

  (NOT in

  .archived/

  )
• Filename matches

  TNNNN-slug.yaml

  pattern
• YAML is syntactically valid
• All six required fields are present

• id

  field matches the TNNNN in the filename

• created

  field is today's date in YYYY-MM-DD format

• priority

  field is exactly

  low

  ,

  medium

  , or

  high

• context

  and

  proposed_work

  fields have meaningful content

Example: Complete Ticket Creation

id: T0001
title: Add search functionality to ticket list
created: 2026-02-01
priority: low
context: |
  As the number of tickets grows, finding specific tickets becomes
  harder. Currently users must read through all ticket files manually.
proposed_work: |
  Create a new skill (search-tickets) that allows filtering tickets by:
  - Title substring match
  - Priority level
  - Date range
  Update list-tickets to optionally use search criteria.

Filename:

T0001-add-search-functionality.yaml

Location:

.ushabti/tickets/T0001-add-search-functionality.yaml

Notes

• Tickets are create-only. Once created, they are not edited.
• If a ticket needs correction, create a new ticket and archive the incorrect one.
• Tickets remain in

  .ushabti/tickets/

  until a derived phase completes, then they are archived.
• Archived tickets are moved to

  .ushabti/tickets/.archived/

  and become invisible to agents.