Skip to content

pivoshenko/pivoshenko.ai / skills/git-issue-create

git-issue-create

Verified

Open one standalone GitHub issue with `gh` - duplicate-checked first, conventional title, repo-template-aware body, auto-resolved labels. Use for every issue-filing request however casual: "open an issue", "file a bug", "make a ticket", "/git-issue-create", "track this", "note this down", "we should fix X later", or whenever the user describes a defect or wanted capability that is clearly not being built right now. A raw `gh issue create` skips the duplicate search, label resolution, and body caps this skill owns. Boundary: work starting now goes to `git-branch-create`; an issue that already exists goes to `git-issue-start`. Creates the issue immediately without asking for confirmation.

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:

IntentCandidate chain
feattype: enhancement -> enhancement -> feature
fixtype: bug -> bug
docstype: documentation -> documentation -> docs
perfperformance -> type: enhancement -> enhancement
refactor / chore / build / citype: maintenance -> maintenance -> chore
testtype: maintenance -> tests -> test
breaking changetype: breaking -> breaking-change -> breaking
dependency bumptype: dependencies -> dependencies -> deps
securitytype: security -> security
prioritypriority: <level> -> <level> priority -> <level>
blockedstatus: blocked -> blocked
duplicatestatus: duplicate -> duplicate
  • 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
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 469kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 321kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 321kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 321kUpdated Claude CodeCodexVerifiedInstall