Create Ticket

Guidelines for creating implementation tickets in

.workaholic/tickets/

.

Frontmatter Template (REQUIRED - DO NOT SKIP)

---
created_at: <run: date -Iseconds>
author: <run: git config user.email>
type: <enhancement | bugfix | refactoring | housekeeping>
layer: [<UX | Domain | Infrastructure | DB | Config>]
effort: <leave empty - filled after implementation>
commit_hash: <leave empty - filled when archived>
category: <leave empty - filled when archived>
---

All fields are mandatory. Run the shell commands to fill

created_at

and

author

.

Filename Convention

Format:

YYYYMMDDHHmmss-<short-description>.md

Use current timestamp:

date +%Y%m%d%H%M%S

Example:

20260114153042-add-dark-mode.md

File Structure

---
created_at: YYYY-MM-DDTHH:MM:SS+TZ
author: <git user.email>
type: enhancement | bugfix | refactoring | housekeeping
layer: [<layers affected>]
effort: <filled after implementation>
commit_hash: <filled when archived>
category: <filled when archived>
---

# <Title>

## Overview

<Brief description of what will be implemented>

## Key Files

- `path/to/file.ts` - <why this file is relevant>

## Related History

<1-2 sentence summary synthesizing what historical tickets reveal about this area>

Past tickets that touched similar areas:

- [20260127010716-rename-terminology-to-terms.md](.workaholic/tickets/archive/<branch>/20260127010716-rename-terminology-to-terms.md) - Renamed terminology directory (same layer: Config)
- [20260125113858-auto-commit-ticket-on-creation.md](.workaholic/tickets/archive/<branch>/20260125113858-auto-commit-ticket-on-creation.md) - Modified ticket.md (same file)

## Implementation Steps

1. <Step 1>
2. <Step 2>
   ...

## Considerations

- <Any trade-offs, risks, or things to watch out for>

Frontmatter Fields

Required at Creation

• created_at: Creation timestamp in ISO 8601 format. Use

  date -Iseconds

• author: Git email. Use

  git config user.email

• type: Infer from request context:

  • enhancement

    - New features or capabilities (keywords: add, create, implement, new)

  • bugfix

    - Fixing broken behavior (keywords: fix, bug, broken, error)

  • refactoring

    - Restructuring without changing behavior (keywords: refactor, restructure, reorganize)

  • housekeeping

    - Maintenance, cleanup, documentation (keywords: clean, update, remove, deprecate)
• layer: Architectural layers affected (YAML array, can specify multiple):

  • UX

    - User interface, components, styling

  • Domain

    - Business logic, models, services

  • Infrastructure

    - External integrations, APIs, networking

  • DB

    - Database, storage, migrations

  • Config

    - Configuration, build, tooling

Filled After Implementation

• effort: Time spent in numeric hours. Valid:

  0.1h

  ,

  0.25h

  ,

  0.5h

  ,

  1h

  ,

  2h

  ,

  4h

  . Invalid:

  XS

  ,

  S

  ,

  M

  ,

  10m

  . Leave empty when creating ticket.
• commit_hash: Short git commit hash. Set automatically by archive script.
• category: Change category (Added, Changed, or Removed). Set automatically by archive script based on commit message verb.

Exploring the Codebase

Before writing a ticket:

• Use Glob, Grep, and Read tools to find relevant files
• Understand existing patterns, architecture, and conventions
• Identify files that will need to be modified or created

Related History

The Related History section is populated by the

history-discoverer

subagent (invoked by

/ticket

command).

Link format: Use markdown links with repository-relative paths:

- [filename.md](.workaholic/tickets/archive/<branch>/filename.md) - Description (match reason)

The full path includes the branch directory from the search results (e.g.,

feat-20260126-214833

).

If the subagent returns no matches, omit the Related History section entirely.

Writing Guidelines

• Focus on the "why" and "what", not just "how"
• Keep implementation steps actionable and specific
• Reference existing code patterns when applicable
• Use the Write tool directly - it creates parent directories automatically