Create Ticket

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