create-ticket

What this skill does

# Create Ticket

Guidelines for creating implementation tickets in `.workaholic/tickets/`.

## Agent Compatibility

This skill works on any Agent-Skills-compatible agent. The two Claude-Code mechanisms used below are **enhancements, not requirements**:

- **Parallel fan-out** — where a step spawns `general-purpose` subagents to run parts concurrently (e.g. the three discovery modes), that is the Claude Code optimization. On other agents, perform those parts **sequentially** in the same session; the inputs and outputs are identical.
- **User interaction** — where a step uses `AskUserQuestion`, use the agent's native way of presenting a multiple-choice question (or ask in plain chat). The decision points are mandatory; only the prompt mechanism varies.

## Allowed Locations

Tickets are written to ONE of these two directories — never anywhere else:

- `.workaholic/tickets/todo/` — Active queue (default for new tickets)
- `.workaholic/tickets/icebox/` — Deferred (only when the request explicitly targets the icebox)

Archive paths (`.workaholic/tickets/archive/<branch>/`) are written by the drive archive script, never by this skill.

**PROHIBITED**: Do NOT write tickets into any other directory under `.workaholic/`, including but not limited to: `RFDs/`, `policies/`, `specs/`, `guides/`, `stories/`, `terms/`, `release-notes/`, `trips/`, `constraints/`, `concerns/`. Even if the user's request sounds like a design discussion, RFD, spec, policy, or carried-over concern, the artifact produced by this skill is a ticket and must live under `.workaholic/tickets/`. Other artifact types (including carry-over concerns/ideas — those are written by `core:ship` and updated by `core:report`) are out of scope for this skill.

**Rationale**: The drive workflow, archive script, navigator, report skill, and validation hook all scan `.workaholic/tickets/` exclusively. A ticket placed in a sibling directory becomes invisible to the rest of the pipeline. The `plugins/work/hooks/validate-ticket.sh` hook enforces this and rejects ticket-shaped files (filename matching `YYYYMMDDHHmmss-*.md`) written outside `.workaholic/tickets/`.

## Step 1: Capture Dynamic Values

**Run the ticket-metadata script:**

```bash
bash ${CLAUDE_PLUGIN_ROOT}/skills/gather/scripts/ticket-metadata.sh
```

Parse the JSON output:

```json
{
  "created_at": "2026-01-31T19:25:46+09:00",
  "author": "[email protected]",
  "filename_timestamp": "20260131192546"
}
```

Use these values for frontmatter fields and filename.

## Frontmatter Template

Use the captured values from Step 1:

```yaml
---
created_at: $(date -Iseconds)      # REPLACE with actual output
author: $(git config user.email)   # REPLACE with actual output
type: <enhancement | bugfix | refactoring | housekeeping>
layer: [<UX | Domain | Infrastructure | DB | Config>]
effort:
commit_hash:
category:
depends_on:
---
```

### Field Requirements

- **Lines 1-4**: Fill with actual values (never placeholders)
- **Lines 5-8**: Must be present but leave empty (filled after implementation, or during creation when a request is split)

### Concrete Example

```yaml
---
created_at: 2026-01-31T19:25:46+09:00
author: [email protected]
type: enhancement
layer: [UX, Domain]
effort:
commit_hash:
category:
depends_on:
---
```

## Common Mistakes

These cause validation failures:

| Mistake | Example | Fix |
|---------|---------|-----|
| Missing empty fields | Omitting `effort:` line | Include all 8 fields, even if empty |
| Placeholder values | `author: [email protected]` | Run `git config user.email` and use actual output |
| Wrong date format | `2026-01-31` or `2026/01/31T...` | Use `date -Iseconds` output (includes timezone) |
| Scalar layer | `layer: Config` | Use array format: `layer: [Config]` |
| Scalar depends_on | `depends_on: file.md` | Use array format: `depends_on: [file.md]` |

## Filename Convention

Format: `YYYYMMDDHHmmss-<short-description>.md`

Use current timestamp: `date +%Y%m%d%H%M%S`

Example: `20260114153042-add-dark-mode.md`

## Workflow

The `/ticket` command (main agent) drives this Workflow directly. Skills cannot invoke subagents or AskUserQuestion directly; the steps below describe what the loading agent (the command) must do. The command issues every AskUserQuestion (moderation decisions, clarifications) and spawns every discovery subagent itself — no `ticket-organizer` subagent sits in between.

### 1. Check Branch

Run `bash ${CLAUDE_PLUGIN_ROOT}/skills/branching/scripts/check.sh`. If `on_main` is true, create a topic branch **only** by running `bash ${CLAUDE_PLUGIN_ROOT}/skills/branching/scripts/create.sh`, and record the returned branch name as `branch_created` for the output JSON.

**Branch-name rule (mandatory):** the branch name is **always** exactly `work-<YYYYMMDD-HHMMSS>`, produced by `create.sh`. Do **not** name a branch yourself, do **not** append a feature/description suffix, and do **not** use any other prefix (`drive-`, `trip/`, a feature name, etc.). `create.sh` is the only branch-creation path.

Already-on-a-topic-branch returns `on_main: false` and skips creation (including legacy `drive-*`/`trip/*` branches, which are still recognized but never created anew); tickets go to `.workaholic/tickets/todo/` regardless of branch type.

### 2. Parallel Discovery

The command spawns three `subagent_type: "general-purpose"` subagents in parallel (single message with three Task calls), `model: "opus"`, one per discovery mode. Each prompt instructs the subagent to preload `core:discover`, run the section matching its mode, and return that mode's output schema:

- **history** (`mode: history` → `core:discover` Discover History): Returns JSON with summary, tickets list, match reasons, and `moderation` field (status/matches/recommendation).
- **source** (`mode: source` → `core:discover` Discover Source): Returns JSON with summary, files list, code_flow, and optional snippets.
- **policy** (`mode: policy` → `core:discover` Discover Policy): Returns JSON with summary, policies list, and architecture (principles, dependency_rules).

These are leaf subagents — they do non-interactive discovery only and MUST NOT call AskUserQuestion. Wait for all three to complete before proceeding.

### 3. Handle Moderation Result

Based on the history discovery subagent's `moderation` field:

- `moderation.status: "duplicate"` — Return `status: "duplicate"` with existing ticket path.
- `moderation.status: "needs_decision"` — Return `status: "needs_decision"` with merge/split options.
- `moderation.status: "clear"` — Proceed to step 4.

### 4. Evaluate Complexity

- **Split when**: multiple independent features, unrelated layers, multiple commits needed.
- **Keep single when**: tightly coupled, shared context, small enough for one commit.
- If splitting: 2-4 discrete tickets, each independently implementable.

### 5. Write Ticket(s)

Follow the rest of this skill for format and content. Apply the Lead Lens table (below) to map the ticket's `layer` field to the relevant `standards:leading-*` skill — its policies, practices, and standards govern the ticket's Implementation Steps, Considerations, and Patches.

Populate sections from the three discovery JSONs:

- **history → Related History**: `summary` field provides the synthesis sentence; `tickets` array provides the bullet list with paths and match reasons.
- **source → Key Files**: `files` array provides paths and relevance descriptions.
- **source → Implementation Steps**: reference `code_flow`.
- **source.snippets → Patches**: generate unified diffs from snippets. Follow the patch guidelines in this skill. Mark patches as speculative if based on interpretation rather than explicit requirements. Omit the Patches section if changes cannot be expressed as concrete diffs.
- **policy → Considerations**: reference relevant `policies` that the implementation must follow; note `architecture.principles` and `architecture.dependency_rules` that constrain the design.

**If splitting**:
- Unique tim