---
name: devhub-create-ticket
description: Create one evidence-grounded XA DevHub work ticket through the authenticated localhost API with exact project resolution, active-duplicate review, mutation preview, strict payload construction, and direct post-write readback. Use when the user asks to create, add, open, file, or draft a DevHub ticket or issue from logs, a diagnosis, review findings, an implementation gap, a bug report, or a feature request.
---

# DevHub Create Ticket

Turn supplied evidence into one actionable DevHub ticket without writing the database directly. Use `$devhub-control` as the only transport and preserve the difference between observed facts, bounded inference, proposed repair, and unrun acceptance gates.

Distinguish a request to save a ticket from a request for a draft to review. For a draft-only request, gather the relevant read-only context and present the proposed payload without calling a mutation. Save it only when the user's request authorizes creation.

## Clarify only essential gaps

Before drafting or saving, check whether the supplied evidence establishes the target project, problem or limitation, expected outcome, and enough scope to define observable acceptance. If a critical answer cannot be recovered from authorized context, use `$devhub-interview` to ask focused questions and pause ticket creation until that answer arrives. Do not create a vague placeholder, invent a requirement, or guess between projects.

Complete requests keep the normal path below. Unknown root cause, optional dates, implementation details, and unrun build or runtime checks are not automatic interview triggers; label them accurately. A request to investigate a known symptom can be actionable without a confirmed cause. Reuse decisions already supplied by the user.

After an interview, refresh health, exact project resolution, and active-duplicate reads before the preview and write; an existing ticket may now cover the request. Preserve creation authority already given, and do not ask for another confirmation solely because an interview occurred. Discussion-only and draft-only requests stop at the brief.

## Workflow

1. Read `$devhub-control` and its API contract before any DevHub action. Resolve that skill's own installed path; do not copy, print, or expose its token.
2. Run `health`. If DevHub is unavailable, stop the ticket operation and report the exact failure. Never open or modify `devhub.db`, and do not invent a fallback ticket file or claim a write succeeded.
3. Run `project-list` and identify one exact active project by its canonical name. If the user gave a path or alias, use it only to choose a candidate, then confirm the exact record with `project-get -Id N`. Use `$devhub-interview` if multiple plausible projects remain; do not guess.
4. Run `work-list -ProjectId N`. Compare active titles and bodies with the new issue's behavior, cause, and requested outcome. If an existing active ticket covers the same work, report its `I<id>` and do not create a duplicate. A similar title with materially different scope is not automatically the same ticket; explain the distinction before proceeding.
5. Apply the essential-gap check above, then draft a complete ticket using the contract below. Use only evidence the user supplied or evidence read from in-scope local sources. Label uncertainty; never turn a hypothesis into a confirmed root cause.
6. Run `work-save -InputJson <payload> -WhatIf`. Inspect the exact target and route shown by PowerShell. If the preview is wrong, correct it before any mutation.
7. Run the same `work-save` call without `-WhatIf`. The control client pre-reads the project and reads the returned work item back by ID.
8. Verify the readback's project, type, title, body, `status=open`, priority, dates, tags, and `origin=api`. Report the canonical `I<id>` plus whether the server created it or recognized an exact replay.

## Ticket contract

Submit every field required by `work-save`:

```json
{
  "project_id": 1,
  "type": "fix",
  "title": "Short actionable title",
  "body": "Structured Markdown body",
  "priority": 3,
  "due_date": "",
  "review_date": "",
  "tags": "reliability,relog"
}
```

- Type: use `fix` for broken existing behavior and `implementation` for new behavior. Use `reference` or `note` only when the user explicitly wants non-actionable knowledge recorded.
- Priority: P4 blocks critical workflows, risks loss or corruption, or is a severe security or reliability failure; P3 is high-impact or broadly blocking; P2 is normal planned work; P1 is low impact. DevHub stores the integer `1` through `4`.
- Dates: leave blank unless the user supplied or authorized a real date. Values must be blank or valid `YYYY-MM-DD`.
- Tags: use a short comma-separated lowercase set; do not invent ownership, release, or completion labels.
- New tickets are always `open`. Do not create directly as `in_progress`, `blocked`, or `completed`.

Structure actionable bug or fix bodies as:

- `## Problem`: user-visible or operational failure and affected scope.
- `## Evidence`: timestamps, IDs, logs, code locations, and what succeeded or failed. Keep excerpts bounded and redact secrets or unrelated personal data.
- `## Cause`: confirmed cause, or `Bounded hypothesis` with the missing evidence needed to confirm it.
- `## Proposed solution`: the smallest durable behavioral change. This is a proposal, not implementation evidence.
- `## Acceptance criteria`: observable outcomes, including failure and retry paths where applicable.
- `## Verification gates`: separate source or static checks, build and tests, runtime, live integration, publication, or other environment gates. Never imply an unrun gate passed.

For a feature request, replace `Cause` with `Current limitation` while keeping the other sections.

## Mutation behavior

The server treats an exact active same-title replay as idempotent and returns the existing ID with `created=false, duplicate=true`. A same-title active ticket with different content is HTTP 409. On conflict, read the existing item, explain the difference, and stop; do not rename the new ticket merely to bypass duplicate protection.

`-WhatIf` is mandatory before creation even when the request appears clear. It is a transport preview, not a ticket write and not proof that the payload will pass server validation.

## Boundaries

- The user's ticket-creation request covers only the requested ticket mutation. This workflow does not expand that scope to implementation, ticket status changes, builds, process starts, Discord messages, publication, commits, or releases.
- Do not use `work-import` to synthesize a new ticket. Historical import and ordinary creation are different operations.
- Do not attach full raw logs when a bounded evidence summary is sufficient.
- If the running DevHub build does not expose `work-save`, report that a rebuilt version with `POST /api/work` is required. Do not bypass the API.