Create Ticket

Create a GitHub issue in this repository. Guides the user through an interactive flow to gather all required information, then creates the issue via gh issue create.

Prerequisites

Before starting the flow, verify gh CLI is available and authenticated:

gh auth status

• If gh is not installed → stop and tell the user: "GitHub CLI (gh) is required. Install it: https://cli.github.com/"
• If not authenticated → stop and tell the user: "Run gh auth login to authenticate first."
• If authenticated → proceed to Step 0

Usage: /create-ticket [type: description | from spec | <change-path> | update <#issue|url>]

Examples:

• /create-ticket — fully interactive
• /create-ticket bug: login page crashes on Safari
• /create-ticket feature: add bulk delete for models
• /create-ticket task: refactor Sidebar for reuse in entity lists
• /create-ticket infra: add LOG_LEVEL to prod
• /create-ticket from spec — from the openspec changes on the current branch
• /create-ticket openspec/changes/archive/2026-06-15-file-dnd-overlay — from a specific change
• /create-ticket update #123 — add details to an existing issue

Step 0 — Intent, Source & Args

First decide which of three modes applies, then parse the remaining args.

• Mode C — Update existing — the user references an existing issue: update, #<number>, or a GitHub issue URL. → go to Update Existing Ticket below.
• Mode B — From spec — the user says "from spec", "from the branch", "issue from current change", or passes an openspec/changes/... folder path. → go to From Spec below, which drafts the Step 2 proposal, then continues at Step 1/3.
• Mode A — From discussion (default) — anything else. Continue with arg parsing here.

Mode A arg parsing

If the user provided arguments after /create-ticket, parse them:

• Look for a type prefix: bug:, feature:, task:, infra: (case-insensitive)
  • bug: → Bug
  • feature: → Feature
  • task: → Task (general engineering)
  • infra: → Task + force infra-task label (shortcut for infra change)
  • If found → set issue type, use the rest as a seed for the title/description
  • If not found → treat the entire arg string as a description seed and ask for type
• If no args at all → start fully interactive from Step 1

When args provide a description seed (or the description comes from the current discussion), use it to:

• Generate a proposed title — concise, under 80 characters
• Generate a proposed summary — a short paragraph followed by key points as a bullet list. For bugs, also draft the actual/expected result from context.
• Pre-fill relevant body fields where obvious
• Auto-assign labels ONLY when the description makes them 100% clear
• For ANY label where assignment is not certain from the description, ask the user directly

From Spec (Mode B)

Build the ticket from the openspec change(s) rather than free description. This produces a User Story + Acceptance Criteria + Definition of Done body, then flows through the normal pipeline (type, labels, priority, assignee, preview, create) so the ticket still gets --project and an assignee.

B1 — Locate the change

• If the user passed a specific openspec/changes/... folder path → use it, skip discovery.

• Otherwise discover changes introduced on the current branch against the repo's base branch (origin/development — NOT main):

  git diff --name-only $(git merge-base HEAD origin/development) -- openspec/

• If no openspec files are found on the branch → tell the user and offer to fall back to Mode A (from discussion). Do not stop silently.

B2 — Read the spec content

For each changed change folder, read (in priority order, all that exist, in parallel):

1. proposal.md — primary: Why, What Changes, Capabilities, Impact
2. design.md — supplementary detail
3. tasks.md — acceptance-criteria hints (checked - [x] = delivered scope)
4. .openspec.yaml — metadata (title, status)

Also read any specs/* files in the diff (openspec/changes/<name>/specs/ or openspec/specs/).

B3 — Synthesise the draft (feeds Step 2)

• Title — from .openspec.yaml title or the proposal heading, under 80 chars.

• Type — derive from the change (default Feature; use Bug/Task if the spec is clearly a fix or engineering task). Confirm in Step 1.

• Summary body — structured as:

  #### User Story
  
  **As a** <persona — end user; "developer" only for tooling/infra>
  **I want to** <one action derived from "What Changes" / capability>
  **So that** <business value from "Why">
  
  #### Acceptance Criteria
  
  - <concise, testable, present-tense: "User can …", "When …, then …"> (aim for 4–8)
  
  #### Definition of Done
  
  - <delivered scope from checked tasks.md items + repo defaults: tests, i18n, RTL, docs where relevant>

Use this as the Step 2 draft, then continue at Step 1 (confirm type) → Step 3 onward. Skip Step 2a code research (the spec already is the research) unless the user asks.

Update Existing Ticket (Mode C)

Add details to an issue that already exists. Default action is to edit the body in place; appending a comment is offered as an option.

C1 — Resolve the target issue

• If args include #<number> or an issue URL → use it.

• Otherwise list candidates and let the user pick:

  gh issue list --search "<keywords from the request>" --limit 10 --json number,title,url

C2 — Fetch current state

gh issue view <number> --json number,title,body,labels,assignees,url,state

Show the user the current title, labels, assignee, and body.

C3 — Gather the new details

Collect what to add from the discussion, or reuse From Spec (Mode B) if the update should come from an openspec change. Determine which of these change: body content, labels, title, assignee, priority.

C4 — Preview the before → after

Show the current vs. proposed body/labels/title so the user sees exactly what changes. Use AskUserQuestion:

"Apply this update?"

Options:

• Edit body (default) — merge the new details into the issue body and update labels/title as needed
• Add comment — keep the body, append the new details as a comment
• Cancel — make no change

C5 — Apply

• Edit body / fields:

  gh issue edit <number> \
    --body "<merged body>" \
    --add-label "<label>" \
    --title "<new title if changed>"

• Or add a comment:

  gh issue comment <number> --body "<new details>"

Use --add-label / --remove-label for label changes; only pass --title/--body when they change. After applying, display the issue URL. Then stop — the rest of the create pipeline (Steps 1–8) does not apply to updates.

Step 1 — Issue Type

Skip if the type was parsed from args. If it was derived from a spec (Mode B), don't skip — confirm the derived type with the user (pre-select it as the default) before continuing.

Use AskUserQuestion to ask:

"What type of issue do you want to create?"

Options (these match the repo's GitHub issue types):

• Bug — Report a problem or defect
• Feature — Request a new feature or enhancement
• Task — Engineering work that is not a user-facing feature (refactor, reuse, tech debt, cleanup, test/build improvements, AND infrastructure changes — env var, secret, config, deployment setting)

Infrastructure changes are NOT a separate top-level type. They're a Task that gets auto-labeled infra-task. Detection happens in Step 3 from context keywords (env var, secret, prod/uat, deployment, config, LOG_LEVEL, etc.).

Step 2 — Title & Summary Proposal

2a. Optional Code Research

Before drafting the proposal, check whether the user's input references code concepts that would benefit from codebase investigation.

Trigger signals (offer the question when ANY are present):

• Verbs: refactor, reuse, extract, consolidate, migrate, rename, split, merge, deduplicate, unify, abstract, move, replace
• Implementation nouns paired with an action: component, hook, utility, service, module, layout, route, page, store, context, provider
• Explicit file paths, component names (e.g., Sidebar), or function/hook names

If triggered, use AskUserQuestion:

"Your request touches code (e.g., refactoring/reuse). Do you want me to dive into the codebase and include relevant details in the ticket?"

Options:

• Yes, research — Explore the codebase and add findings to the description
• No, skip — Proceed without code research

If Yes, spawn an Explore agent (via the Agent tool with subagent_type: Explore) to find:

• Current location(s) of the subject code (file paths with line references)
• Similar or duplicated patterns elsewhere in the codebase
• Files/components/consumers that would be affected by the change
• Existing conventions or abstractions to align with
• If hand-authored libs/* are involved, the app/lib boundary: host-owned integration details such as API paths, generated clients, server-api wrappers, auth/session/cookie/env details, feature flags, routes/navigation, analytics/telemetry/logging, SDK setup, platform bridges, and app-specific storage keys/schemas must stay outside libs
• If libs/chat-api-client is involved, call out that it is generated by OpenAPI scripts and should not be hand-edited

Keep the summary concise — bullet points with path:line references, not prose walls. These findings feed into 2b (title sharpness, description clarity, and a new Details section in the body).