Git Issue Create

File one standalone issue. No confirm.

Flow

1. Boundary check: is the work starting now? Yes -> hand off to git-branch-create (new work) or git-issue-start (issue already exists) and stop. Why -> an issue is a record of work deferred; work in flight belongs on a branch, and a second tracker entry for it just rots
2. Repo: gh repo view --json nameWithOwner -q .nameWithOwner. Fails -> stop, surface the error (no remote, no auth, not a repo). Never guess owner/name
3. Search for duplicates before drafting anything:

   gh issue list --search "<2-4 distinctive keywords>" --state all --limit 10 \
     --json number,title,state,url -q '.[] | "\(.number)\t\(.state)\t\(.title)"'

   --state all -> a closed issue is the answer often enough that skipping it files the same bug twice. Keywords are nouns from the user's description, not the whole sentence. 10 hits returned -> the search was too broad and real duplicates may sit past the cap; narrow the keywords and search again before proceeding
4. Triage the hits:
   • Strong match (same defect, same capability) -> print its number, title, state, URL. Stop. Offer to comment on it instead (<= 4 prose lines, see Length); reopening is the user's call, not this skill's. Why -> a duplicate backlog is worse than a missing issue: every triage pass afterwards pays for it
   • Adjacent match (related, not the same) -> proceed, link it in ## Context
   • No hits -> proceed
5. Parallel:
   • Repo issue template: .github/ISSUE_TEMPLATE/*.md, .github/ISSUE_TEMPLATE/*.yml, .github/issue_template.md, root issue_template.md (first match wins)
   • gh label list --limit 200 --json name -q '.[].name'
6. Draft title per Title. Draft body:
   • Template found -> fill that template's structure (preserve headings, order, checklists, HTML comments). A *.yml form -> render its label/attributes as markdown headings in the same order
   • None found (the normal case) -> use Fallback Body below
7. Resolve labels per Labels. Exactly one type: *
8. Heredoc body so markdown survives the shell:

   gh issue create --title "fix(auth): session drops on api deploy" --label "type: bug" --body "$(cat <<'EOF'
   ## Problem
   
   Sessions drop on every API deploy because the cookie is signed with a per-instance key.
   
   ## Done when
   
   - a session survives a rolling restart of all API pods
   - no change required to the `users` table
   EOF
   )"

   'EOF' quoted -> no shell interpolation, so $, backticks and # in the body survive intact
9. Print the issue URL. Name any label dropped in step 7 and why
10. User wants to start on it now -> hand off to git-issue-start

Title

Same grammar as git-commit and git-pr-create:

<type>(<scope>): <short summary>

• Type: build|chore|ci|docs|feat|fix|perf|refactor|test. Type picks and tiebreakers live in git-commit - use that table, do not re-derive one
• Scope: optional, lowercase, one only
• Summary: imperative present, lowercase, no trailing .
• Whole title <= 72 chars

The title is the type signal: fix( is what makes type: bug the obvious label in step 7.

Examples:

• fix(api): handle timeout on retry
• feat(catalog): filter skills by tag
• docs(readme): document the sync contract

Labels

Never hardcode the namespaced taxonomy - detect it. These rules run on forks and third-party repos too.

Fetch once per run:

gh label list --limit 200 --json name -q '.[].name'

Resolve each intended label through its candidate chain, first existing name wins:

• Whole chain missing -> drop that label and say so in the output. Never gh label create
• Exactly one type: * per issue. Pick the dominant type, never two
• priority: * only when the user signalled urgency. Never guess a priority
• Multi-word names must be quoted: --label "type: bug"

Body - Repo Template Present

• Template verbatim as the skeleton: headings, order, checklist items, HTML comments
• Fill only the fields the user actually gave you. A required field you cannot answer -> ask, do not invent
• Tick checklist items that apply; leave the rest unchecked
• *.yml form with a labels: key -> those labels are additive to step 7, and still go through the candidate chains

Fallback Body

No template found - the normal case. Fill references/issue-body.md.

Optional, only when it carries a fact:

• ## Context - <= 2 lines, links to prior issues, PRs, ADRs
• ## Out of scope - <= 2 lines, the adjacent thing a reader would otherwise assume is included

Never emit an empty placeholder section. Drop it.

Acceptance criteria you were not told -> ask, or omit ## Done when. Why -> an invented criterion is worse than a missing one: it closes the issue on the wrong condition.

Length

Hard cap: 8 lines of prose for an issue body, 4 for a comment on an existing one. Headings and code blocks don't count - only text you write.

• ## Problem: 1-3 lines. What is wrong and what it costs. Not the fix
• ## Done when: one bullet per condition, one line each, 100 chars or fewer. No sub-bullets, no paragraph bullets
• Any other section: <= 2 lines, or drop it
• Nothing to say -> drop the section. An empty section is information, filler is not

Prohibitions:

• Why it exists and what "done" means, not how - the code shows how
• No restating the title. The reader just read it
• No play-by-play ("first X, then Y"). No file inventories, no code dumps
• Never invent acceptance criteria, paths, or repro steps. Unknown -> ask or omit

Good:

## Problem

`kst sync` silently skips new MCP files because `kasetto.yaml` enumerates them by name.

## Done when

- adding `mcps/<name>.json` syncs without editing `kasetto.yaml`
- the site and the sync agree on which MCPs exist

Bad - filler opener, restates the title, narrates the work, invents criteria:

## Problem

This issue tracks the comprehensive implementation of a more robust MCP sync
mechanism. Currently the existing configuration leverages an enumeration-based
approach which presents certain challenges.

## Done when

- First we will investigate how kasetto.yaml is parsed
- Then we will design a holistic solution
- Finally we will ensure that all 6 MCP servers sync seamlessly

Rules

• Duplicate search runs before the body is drafted. Why -> drafting first makes you argue for filing it
• Strong duplicate -> stop and surface it. Never file a near-duplicate "to be safe"
• Never gh label create. Chain missing -> drop the label, report it
• Exactly one type: * label. Two type labels break every triage query
• Never invent acceptance criteria, file paths, numbers, or repro steps. Unknown -> ask or omit
• Never --assignee / --milestone / --project unless asked. Self-assigning implies you are starting, which is git-issue-start
• Body over 8 prose lines -> cut before creating, not after
• One issue per invocation. A list of separate problems -> one issue each, filed one at a time
• Never close or edit an existing issue from this skill
• No "Generated with Claude Code" or co-author trailers