github-cr-issue

Create Issue (GitHub)

Draft the body of one well-formed, non-ADR issue as an ephemeral local file, ready to be reviewed and then published as a GitHub issue by github-post-issue.

A good issue records one topic in a self-contained way. GitHub is the project's state store, agent sessions are stateless workers, and the published issue is the complete spec — any future contributor or agent session must be able to read and act on it with zero private context.

This skill always operates on the repository it is invoked in — the repo is detected dynamically in step 1 and never assumed.

When to use

• The user asks to create, draft, or write an issue — a feature, component, task, bug, or spike.
• A discussion, idea, or defect report needs to become a tracked, actionable GitHub issue.
• A large initiative needs structuring as a parent issue with sub-issues.

Skip if

Issue types

Pick exactly one type per issue.

There is no epic template. For an umbrella initiative, draft a parent issue (usually a feature) and separate child issues, then attach the children through GitHub's native sub-issue relationships at publish time. An epic written as a document duplicates state the child issues already carry and rots as they evolve; the relationship graph stays current because it is maintained where the work happens.

Component issues

Use component when the deliverable is a reusable building block other work will consume, rather than an end-user capability. A component has a defined contract: one clear responsibility, named inputs and outputs, and an explicit boundary against sibling components. If the component's design still needs deciding, open the decision first with github-cr-adr and reference it by its ADR number with the issue linked — the decision holds the design; the component issue tracks the build.

The template's deliverables checklist is deliberately generic — implementation, documentation, consumer wiring, tests — so tailor each item to the repository's own layout when filling it in.

Workflow

1. Detect the repository

The skill operates on whatever repository the user is working in — never assume an owner or name:

REPO=$(gh repo view --json nameWithOwner -q .nameWithOwner)
# Fallback when gh cannot resolve the repo:
[ -z "$REPO" ] && REPO=$(git remote get-url origin | sed -E 's#(git@|https://)github.com[:/]##; s#\.git$##')

2. Search for duplicates — before drafting anything

Catching a duplicate now costs one search; catching it at publish time costs a fully written body:

gh issue list --repo "$REPO" --search "<topic keywords>" --state all --limit 20
# e.g. for a retry mechanism on failed imports:
#   --search "retry import"   then   --search "failed ingestion"

Run the search two or three times with different keyword sets — title nouns, synonyms, the affected subsystem's name — because existing titles rarely match the new phrasing exactly. Keep --state all: a closed issue on the same topic is history the new one must acknowledge. If gh is missing or unauthenticated, say so and continue drafting — dedup is a read-time optimization here and runs again as a hard gate at publish.

On a hit, stop and propose one of these instead of a new draft:

Continue to a new draft only when the topic is genuinely uncovered, or the user explicitly confirms the existing issue does not apply.

3. Pick the type and confirm the scope is one topic

Choose one type from the table above. If the request bundles several topics, split it — one issue per topic, or one parent with sub-issues — because a bundled issue cannot be closed, assigned, or prioritized cleanly. If the request is epic-scale, draft the parent and each child as separate files; the hierarchy is attached natively at publish time, never written into the bodies.

4. Copy the template block and fill it

Copy the matching block from assets/issue-templates.md and fill every placeholder. Keep the section headers inside the template exactly as given — a predictable structure is what makes issues scannable across the whole tracker. The ## `[TYPE]` marker line that opens each block is a selector for that file, not issue content — never include it in the body.

Per-type quality bar:

5. Run the self-containment pass

The published issue must be readable with zero private context, so strip or translate before handing off:

Test: would a stranger who just cloned the repository understand and act on this issue alone?

6. Save the draft

mkdir -p .claude/sdd/drafts
# Save as: .claude/sdd/drafts/<type>-<slug>.md

The slug is the title in lowercase-with-hyphens (feature-retry-failed-imports.md), with no status markers or internal labels — the filename only needs to identify the draft until it is published.

The draft is ephemeral. It exists to be reviewed and then consumed by github-post-issue, which deletes it after a successful publish — the published issue is the canonical record, never the local file. A draft the author is not ready to take public stays in the file only; publishing is an explicit decision by whoever owns the issue.

Treat the drafts directory as a queue, not an archive — a draft that lingers unpublished should be published or deleted, because stale drafts drift from the tracker they were written for.

7. Hand off for review and publication

Present the draft path and a short summary to the user for review. Publication belongs to github-post-issue: it re-runs the dedup and self-containment guardrails, validates and applies labels, sets native parent/sub-issue relationships, creates the issue, and deletes the draft.

Output of this skill: one draft file per issue under .claude/sdd/drafts/ — nothing is posted to GitHub.

Content rules

Add an ASCII or Mermaid diagram when layout matters — future readers cannot ask follow-up questions.

References

Related skills

• github-cr-adr — drafts Architecture Decision Records; use it when the work is deciding an architecture, not building one.
• github-post-issue — publishes the reviewed draft: labels, relationships, guardrails, then deletes the draft file.