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: ```bash 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]` 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` --- ## Step 0 — Parse Args 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 `ops-request` 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, 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 --- ## Step 1 — Issue Type Skip if parsed from args. 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 `ops-request`. 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 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). ### 2b. Draft the Proposal Based on the user's input, answers so far, and any code research findings: 1. **Propose a title** — concise, under 80 characters. If research was done, make it specific (e.g., "Refactor `Sidebar` for reuse in `ModelList`, `AdapterList`, `UserList`"). 2. **Propose a summary** — structured as: - A short description paragraph (1-3 sentences explaining *what* and *why*) - **Key points** as a bullet list extracting the important details - For **bugs**: also include drafted "Actual result" and "Expected result" if enough context exists - If code research was done: a **Details** section listing current location, affected files, duplicated patterns, and recommended scope (with `path:line` references) 3. **List all labels** that will be auto-assigned based on the issue type and any labels already determined from context (e.g., `bug`, `Design Required` if obvious from description). Mark labels that will be asked about later as "TBD". Present the proposal to the user and ask for confirmation: > "Here's what I've drafted from your input: > > **Title**: `<proposed title>` > > **Summary**: > <description paragraph> > > Key points: > - <point 1> > - <point 2> > - ... > > **Labels (planned)**: > - `label1` (auto) > - `label2` (auto) > - Priority — TBD > - Severity — TBD > - ... > > Want to use this, or change anything?" Options: - **Use as-is** — proceed with this draft - **Edit** — I want to change something If **Edit**: ask what they want to change, revise, and re-confirm. The proposed summary becomes the main content of the description/body field. **IMPORTANT**: If the user approves the draft ("Use as-is"), do NOT re-ask fields that were already covered in the draft. In Step 3, only ask for fields that are missing or were not part of the proposal. For example, if the draft already includes "Actual result" and "Expected result" for a bug, skip those questions and only ask for remaining fields (version confirmation, steps to reproduce, severity, etc.). --- ## Step 3 — Type-Specific Fields Before asking individual fields, if the draft from Step 2 already covers some fields, ask the user: > "The draft already covers some details. How do you want to proceed?" Options: - **Use draft, fill remaining** — Accept drafted fields, only ask for missing ones (version, severity, etc.) - **Provide details now** — Go through each field interactively - **Use draft as-is** — Skip all type-specific questions, use drafted content for all fields and fill missing fields with reasonable defaults or "_No response_" Gather information interactively based on the issue type. Ask each field as a separate question using **AskUserQuestion** (open-ended, no preset options) unless a dropdown/choice is specified. ### Bug 1. **Version**: Auto-detect by reading the `version` field from the root `package.json`. Confirm with user: > "The current version is `<version>`. Is this the version where you see the bug?" 2. **Steps to reproduce**: Ask: > "How do you reproduce this bug? Provide step-by-step instructions." 3. **Actual result**: Ask: > "What happens currently? (the broken behavior)" 4. **Expected result**: Ask: > "What should happen instead?" 5. **Additional information** (optional): Ask: > "Any additional context? (screenshots, logs, browser info — or skip)" 6. **Severity**: Use **AskUserQuestion** with options: - **Critical** — Severe issue impacting core functionality, requires urgent resolution - **Major** — Affects many users or key components - **Minor** — Minor issue with limited impact - **Low** — Low issue with little to no critical impact ### Feature 1. **Description**: Ask: > "Describe the feature. What should it do and why is it needed?" 2. **Related issues** (optional): Ask: > "Are there any related issues? (paste issue numbers/URLs or skip)" ### Task Covers engineering work (refactor, reuse, tech debt, cleanup, test/build improvements) AND infrastructure changes (env var, secret, config, deployment setting). **Step 3.0 — Infra sub-classification** Before gathering fields, detect whether this Task is an infrastructure change. **Infra signals** (auto-apply `ops-request` label when ANY are present): - Keywords: environment variable, env var, secret, credential, config change, deployment, `LOG_LEVEL`, `NODE_ENV`, prod / uat / development, Kubernetes, Helm, CI/CD, pipeline - The user invoked `/create-ticket infra: …` (args prefix forces ops-request label) - The description only describes a runtime/config change with no code change If infra signals are clearly present → auto-apply `ops-request` label (tell the user), go to the infra field set below. If genuinely ambiguous → use **AskUserQuestion**: > "This looks like a Task. Is it an infrastructure change (env var, secret, config, deployment)?" Options: **Yes, infra** (adds `ops-request` label) / **No, general task** **General Task fields** (no `ops-request` label): 1. **Description**: Ask: > "Describe the task. What needs to change and why? (problem/motivation)" 2. **Acceptance criteria** (optional): Ask: > "List acceptance criteria or sub-tasks as checklist items (one per line), or skip." Format each as `- [ ] <item>` in the body. 3. **Related issues** (optional): Ask: > "Are there any related issues or PRs? (paste numbers/URLs or skip)" **Infra Task fields** (`ops-request` label auto-applied): 1. **Change type**: Use **AskUserQuestion** with options: - environment variable - secret - config change - extra configuration - other 2. **Target environment**: Use **AskUserQuestion** with options: - development - uat - production - all 3. **Task list**: Ask: > "List the changes needed as checklist items (one per line)." Format each as `- [ ] <item>` in the body. 4. **Context / reason** (optional): Ask: > "Why is this change needed? Link to a ticket, incident, or PR if applicable. (or skip)" --- ## Step 4 — Priority Use **AskUserQuestion**: > "What priority level?" Options (map to the repo's `P#` labels — note the exact label text includes the en dash ` – `): - **Critical** — Feature or system completely broken for all users, no workaround → `P1 – Critical` - **High** — Broken for a specific segment; workaround exists but inconvenient → `P2 – High` - **Medium** — Secondary flow/UX degraded, reasonable workaround → `P3 – Medium` - **Low** — Cosmetic or edge-case, trivial/no workaround needed → `P4 – Low` --- ## Step 5 — Conditional Labels Evaluate the description and context gathered so far. For each label below: - If it is **100% clear** from context that the label applies → auto-assign it and inform the user - If it is **uncertain** → ask the user directly ### Design Required Auto-assign **yes** if the user explicitly mentions: new page, new UI component, layout change, redesign, UX change, new visual element. Auto-assign **no** (skip the question entirely) when the context clearly has no design implications — e.g., crashes, errors, backend issues, config changes, refactoring, performance bugs, infra tasks. Only ask the user when it's genuinely ambiguous (e.g., "improve the user list" — could be UX or just data): > "Does this issue require design work?" Options: Yes / No ### Security Impact Analysis This repo has **no** `SIA-*` labels, so security impact is **not** captured via a label. If the user mentions a security-relevant surface (authentication, authorization, tokens, secrets, passwords, permissions, session, credentials, encryption, PII), note "Security impact: needs review" in the issue **body** instead of applying a label. Do not attempt to add an `SIA-required` / `SIA-not required` label — creation will fail (`label not found`). ### Area label (optional) The repo has area labels — `analytics-2.0`, `eval`, `cli`, `ui-kit`. When the issue clearly belongs to one area, offer to add the matching label (e.g. an Analytics feature → `analytics-2.0`). Only apply when confident; otherwise skip. --- ## Step 6 — Assignee A ticket MUST have an assignee — never leave one unassigned (tickets without owners get lost). Default to the creator (`@me`). Use **AskUserQuestion**: > "Assign to you (the creator) by default, or someone else?" Options: - **Me (default)** — Assign to the creator (`@me`) - **Someone else** — Ask for a GitHub username If **Someone else**, ask: > "GitHub username to assign?" --- ## Step 7 — Preview Show the user a formatted preview of the entire issue: ``` ══════════════════════════════════════════ ISSUE PREVIEW ══════════════════════════════════════════ Title: <title> Type: <Bug/Feature/Task> (reflected via labels) Labels: <comma-separated list — includes `ops-request` if this is an infra change> Assignee: <@me (creator) / username> ────────────────────────────────────────── BODY: ────────────────────────────────────────── <formatted body matching template structure> ══════════════════════════════════════════ ``` Use **AskUserQuestion**: > "Create this issue?" Options: - **Create** — Create the issue now - **Edit** — I want to change something - **Cancel** — Don't create the issue If **Edit**: Ask what they want to change, update it, and show the preview again. If **Cancel**: Stop and confirm cancellation. --- ## Step 8 — Create Build and execute the `gh` command: ```bash gh issue create \ --title "<title>" \ --body "<body>" \ --label "<label1>,<label2>,..." \ --assignee "<@me|username>" ``` Notes: - `--type` is not supported by `gh issue create`. Issue type (Bug/Feature/Task) is conveyed via labels (`bug`, `enhancement`, or task-specific labels) — there is no separate type flag. - There is no separate "Infra Task" type — infrastructure work is a Task with the `ops-request` label auto-applied and the infra-specific body structure (change type, target environment, task list). - `--assignee` is always set (default `@me`), so every ticket lands with an owner rather than in an unassigned backlog. - The `<details-section>` placeholder in the templates below is the code-research findings from Step 2a. If research was NOT performed, omit the entire `### Details` heading and its content — do not leave an empty section. - The body must be formatted to match the GitHub issue template output format: **Body formats:** `references/issue-bodies.md` holds the exact per-type body structure (Bug, Feature, Task, infra Task). Read it before composing the body — the headings must match the repository's issue templates verbatim. After successful creation, display the issue URL returned by `gh`. --- ## Label Reference `references/labels.md` holds the verified label table for this repo. `gh issue create` fails hard on an unknown label, so confirm against it — or `gh label list --limit 300` — before applying. ## Guardrails - Creating an issue is outward-facing and awkward to undo: show the preview and get explicit confirmation first, every time. - Only apply a label you are certain of. `gh issue create` fails outright on a label this repo doesn't have, and a wrong-but-valid label quietly misroutes the ticket. - When uncertain about ANY label, ask directly — don't guess - Always use the exact label names as listed in the Label Reference table - The confidential information checkbox is always pre-checked in the body - If `gh` CLI fails, show the error and suggest the user check their auth (`gh auth status`)