Create Ticket

create-ticket

This repo's existing large tickets (#613, #617, #622) accumulated day-by-day plans, duplicate "resolved/unresolved decisions" tables, and inline strikethrough history until they became hard for anyone — human or Claude — to actually use. This skill exists to stop that pattern from recurring: every new ticket gets scoped to one unit of work and written in one fixed shape.

Before drafting

Gather (ask the user via AskUserQuestion if not already clear from the conversation):

1. The problem/need — not the title restated, the actual "why."
2. Parent issue, if this is part of a larger ticket (Part of #N). Omit if standalone.
3. Design/doc links (Figma, Drive, etc.), if any — these get referenced as bare pointers, never pasted/embedded as content.

Template — follow exactly, no extra sections

Part of #<parent>            <!-- omit this line entirely if standalone -->

## Why
2-4 sentences. The problem or need driving this ticket, not a restatement of the title.

## Scope
One sentence naming the single unit of work this issue covers.

## Acceptance Criteria
- [ ] Short, independently-verifiable checklist items

## Out of Scope
- Adjacent things this issue deliberately does NOT cover, with a pointer to where they ARE tracked (another issue number, or "not yet tracked")

## Links
- Design/doc links as bare URLs only — no embedded tables, screenshots-as-text, or copy-pasted doc content

Scope-creep guard — check before creating

If the drafted issue would need more than ~8 acceptance criteria, or the "Why" section is actually describing more than one unrelated concern, stop before creating it. Say so explicitly and propose splitting into multiple issues instead (one per unit of work, each Part of #<same parent> if applicable). This check is the actual point of this skill — it's the direct fix for how #613 and #617 grew unmanageable. Don't skip it because splitting feels like extra work up front; it's cheaper than the alternative.

Do not add: day-by-day plans, "resolved decisions" / "decisions still needed" tables, embedded design mockup descriptions, or strikethrough-tracked history. If a decision needs to change after the ticket is created, edit the Acceptance Criteria directly or leave a comment — don't accumulate a decision log inside the issue body.

Creating the issue

Once the body is drafted and passes the scope-creep guard, create it with gh issue create -R willowtreeapps/vocable-android --title "<title>" --body "<drafted body>".

Creating and linking the branch

Sub-issue tickets whose PR will target a parent integration branch (e.g. feature/voice-selection — the normal case per CLAUDE.md's sub-issue convention) must use createLinkedBranch to show up under the issue's "Development" section. Closes #N does not link or auto-close when the PR's base isn't the repo's default branch (closingIssuesReferences comes back empty, willCloseTarget: false) — confirmed on #653/#654. There is also no mutation to attach an already-existing branch/PR after the fact — createLinkedBranch only creates a new ref, it can't adopt one. So call it first, before pushing any branch with that name; if a plain branch is pushed first, the only fix is deleting and recreating both the branch and PR.

1. Get the issue's node ID (same query as "Adding it to the board" step 1), the repository's node ID, and the base commit to branch from (the tip of the parent's integration branch, e.g. feature/voice-selection, or main for a standalone issue with no parent):

   git rev-parse origin/<base-branch>
   gh api repos/willowtreeapps/vocable-android --jq '.node_id'

2. Create + link the branch in one call (name follows the usual feature/<issue-number>/<short-description> convention) — needs write access to the repo (fails with FORBIDDEN: does not have the correct permissions if missing, a distinct failure from the project-scope INSUFFICIENT_SCOPES case below):

   gh api graphql -f query='
   mutation($issueId: ID!, $oid: GitObjectID!, $name: String!, $repositoryId: ID!) {
     createLinkedBranch(input: {issueId: $issueId, oid: $oid, name: $name, repositoryId: $repositoryId}) {
       linkedBranch { ref { name } }
     }
   }' -f issueId="<issue node id>" -f oid="<base commit SHA>" \
      -f name="feature/<issue-number>/<short-description>" -f repositoryId="<repo node id>"

3. Fetch and check out the branch it just created, instead of creating a new local one:

   git fetch origin feature/<issue-number>/<short-description>
   git checkout feature/<issue-number>/<short-description>

Standalone issues targeting main don't have this problem — Closes #N works normally there — but every sub-issue in this repo's workflow targets a parent branch, so treat createLinkedBranch-first as the default.