ticket-creator

Ticket creator

Create well-structured tickets that the ticket-worker skill can consume without ambiguity.

Ticket format contract

Every ticket must have:

Good ticket example

tk create "Fix token refresh returning 401 on expired tokens" \
  -d "The /auth/refresh endpoint returns 401 when the refresh token is expired.
Should return 403 with a clear error message instead.
Relevant code in src/auth/refresh.ts and src/auth/middleware.ts." \
  --acceptance "1. POST /auth/refresh with expired token returns 403 (not 401)
2. Response body includes 'error' field with descriptive message
3. Existing tests pass
4. New test covers expired token case" \
  -t bug

Bad ticket example

tk create "Fix the bug" -d "There's a bug somewhere in auth"

No acceptance criteria, no file hints, no verification command. The agent will wander.

Acceptance criteria guidelines

• Each criterion must be independently verifiable
• Prefer criteria that map to a command: "tests pass", "linter clean", "curl returns X"
• Always include "existing tests still pass" as one criterion (unless no tests exist)
• For refactors: "behavior unchanged" + "tests pass" is sufficient
• Never use vague criteria like "code is clean" or "well-structured"

Parent vs dependency

Use --parent when one ticket is a logical subtask of an epic (e.g., "implement login form" under "add auth system"). Use dep when two tickets are independent work items where one must finish before the other starts. When in doubt, use dep — it's the more common relationship.

Only add dep when there is a real ordering constraint (e.g., ticket B requires code that ticket A will create). If two tickets could be worked on in parallel, do not link them with deps.

Tagging rule

Only add --tags ready-for-development when the ticket is fully refined: description, acceptance criteria, and file hints are all present. Vague or wishlist tickets should have no tag — they live in the backlog until refined.

Refining is done via Mode 4 — do not hand-edit YAML frontmatter.

Size rule

A single ticket should be completable in one agent session (~30 min of agent work). If a task is larger, split it into multiple tickets with dependencies.

Modes

Mode 1: single ticket

User says: "create a ticket for X" or "add a ticket for X"

1. Clarify scope if ambiguous
2. Explore the codebase to find relevant files
3. Create the ticket
4. Commit the ticket: git add .tickets/ && git commit -m "feat(tickets): add ticket for <short description>"
5. Show the created ticket to the user

If the request is vague ("add a ticket for that auth thing I mentioned"), create a backlog ticket: brief title, minimal description, no tag. The user or a later refine session will fill in the details.

If the request is specific enough to write proper acceptance criteria and file hints, create a fully-formed ticket with --tags ready-for-development.

Mode 2: decompose

User says: "break this goal into tickets" or "create tickets for refactoring X"

1. Understand the full goal
2. Explore the codebase to understand scope and relevant files. If lat.md/ exists at project root, run lat search "<goal description>" to discover relevant context from the knowledge graph
3. Seed context file if it doesn't exist (see "Context seeding" below)
4. Break into small, independently completable tickets
5. Create tickets in dependency order (create the prerequisite tickets first so you have their IDs)
6. Set dependencies: tk dep <downstream-id> <upstream-id> (downstream depends on upstream)
7. Validate the dep graph: tk dep cycle and tk ready — if there are cycles or no ready tickets, fix before proceeding
8. Show all created tickets and their dependency chain

Mode 3: seed from plan

User says: "seed tickets from this plan" or provides a plan file path

1. Read the plan file
2. Explore the codebase to understand scope and relevant files. If lat.md/ exists at project root, run lat search "<goal description>" to discover relevant context from the knowledge graph
3. Seed context file if it doesn't exist (see "Context seeding" below)
4. Identify discrete work items
5. Create tickets for each, preserving the plan's ordering via dependencies
6. Show the created tickets

Mode 4: refine

User says: "refine ticket X" or "refine backlog tickets"

Turn a vague backlog ticket into a workable one. If the ticket is too large, split it first (Mode 2).

1. Read the ticket: tk show <id>
2. If the ticket already has ready-for-development tag, tell the user it's already refined and stop
3. Explore the codebase to find relevant files, understand scope, and gather context
4. If the ticket is unclear, ask the user for clarification before proceeding
5. Rewrite the ticket file with:
   • Clear title (imperative, scoped)
   • Description with what to do, why, and file hints
   • Numbered acceptance criteria (each independently verifiable)
   • Correct type if the current one is wrong
6. Add the ready-for-development tag to the frontmatter
7. Commit the refined ticket: git add .tickets/ && git commit -m "refactor(tickets): refine ticket <id>"
8. Show the refined ticket to the user

Batch refine: if the user says "refine backlog tickets" or "refine all", repeat for each untagged open ticket. Stop on the first one that needs user clarification — don't guess.

To rewrite a ticket file, use the write tool on the file path shown by tk show. Preserve the existing YAML frontmatter fields (id, created, deps, links, parent) and only update: title, description, acceptance criteria, type, tags.

Context seeding

Modes 2 and 3 create a context file to avoid redundant discovery in each ticket-worker session.

Prerequisite: if a lat.md/ directory exists at the project root, skip context seeding entirely. The lat search command (run in step 2) provides living, queryable context that makes a static context file redundant.

After exploring the codebase (step 2 in both modes), check if plans/.ticket-context.md exists. If it does, skip — the context is already seeded. If not, create it:

mkdir -p plans

Write plans/.ticket-context.md with three sections:

## Verification commands

- Build: <command>
- Test: <command>
- Lint: <command>

## Key directories

- path/ — description

## Conventions

- Description of relevant patterns

Fill in each section from what you discovered during exploration:

• Verification commands: look in devenv.nix (scripts, tasks, git-hooks), package.json (scripts.test, scripts.lint, scripts.build), Makefile (test, lint, check, build targets), flake.nix (checks)
• Key directories: list directories relevant to the batch of tickets being created
• Conventions: notable patterns found during exploration (error handling style, file structure, naming)

The context file is project-local and reusable across all tickets in the batch.

Self-validation (always run after Mode 2/3)

After creating all tickets, run these checks:

1. tk list — confirm all tickets are open
2. For each ticket: tk show <id> — verify:
   • Description has file hints
   • Acceptance criteria are numbered and independently verifiable
   • If any are vague, refine immediately (Mode 4)
3. tk dep cycle — no cycles allowed. If found, fix.
4. tk ready -T ready-for-development — at least one ticket must be unblocked
5. If no tickets are ready, fix dependency ordering

Report: number of tickets created, any issues found and fixed, whether tickets are ready for work.

Workflow

1. Read the user's request
2. Explore the codebase to understand relevant files and context
3. Draft ticket(s) mentally — title, description with file hints, acceptance criteria
4. Create tickets via tk create with all fields populated. Use real newlines in -d and --acceptance arguments — never pass literal \n characters
5. If multiple tickets: set dependencies via tk dep <id> <dep-id>
6. Run self-validation (see above)
7. Commit all created tickets: git add .tickets/ && git commit -m "feat(tickets): add tickets for <short description>"
   • If .tickets/ is not the tickets dir, find it first with find . -name .tickets -type d
   • Also commit any context file created (plans/.ticket-context.md)
8. Present created tickets for review