create-issue

name

create-issue

description

Turn a rough request into a well-formed GitHub issue that's ready for the auto-dev pipeline. Takes the user's description, then either investigates the codebase to isolate the affected files, likely root cause, and repro — or asks targeted clarifying questions when the ask is underspecified — and drafts an issue with a crisp problem statement, acceptance criteria, and concrete file/symbol pointers. Dedups against existing issues, shows the draft for confirmation, files it, and labels it so auto-dev's triage can pick it up. Reads the repo config for the repo slug, source paths, and (when auto-dev is enabled) the pipeline labels. Use when the user wants to "create/file/open an issue", "turn this into an issue", "file a bug / feature request", or "write up an issue for X". Do NOT use to browse or triage existing issues, or when the user only wants an in-chat answer without filing anything.

Create a pipeline-ready issue

This skill is the front door to the auto-dev pipeline: it turns a rough request — "X is broken", "we should add Y" — into a GitHub issue well-formed enough that the pipeline can actually build it. An autonomous builder is only as good as the issues fed into it; a vague issue wastes a whole build cycle or sends it sideways. The value here is the grounding: real file/symbol pointers, concrete acceptance criteria, and a tight scope, produced by reading the code — not by transcribing the user's one-liner into a bug template.

It's the intake stage of the pipeline (create-issue → auto-dev builds → review-queue), and it's useful on its own even where auto-dev isn't enabled: a well-scoped issue is worth filing regardless.

Load the repo config

Read .claude/maintainerd.json (see ../../../core/reference/config-schema.md); if missing, stop and tell the user to run /bootstrap.

Keys this skill uses:

• config.repo — GitHub owner/name for every gh call.
• config.paths.source — where to investigate to ground the issue in real pointers.
• config.autoDev.enabled — if true, align labels so the pipeline's triage picks the issue up (below). If false/absent, just file a well-formed issue; skip the pipeline-specific labeling.
• config.autoDev.stateLabels.* — the auto:* state labels (only used if the user wants to fast-track; default is to leave the issue for auto-dev's own triage).
• config.autoDev.excludedLabels — labels that make auto-dev skip an issue (e.g. epic, question). Apply one of these when the request isn't a single buildable unit.

Workflow

1. Understand the request

Read what the user gave you and classify it: bug, feature/enhancement, refactor/chore, or question (a question usually shouldn't become a build issue — answer it or file it labeled to be excluded). Note what's already concrete and what's missing for a buildable issue: a bug needs a repro

• expected/actual + the code path; a feature needs the desired behavior + acceptance criteria + where it plugs in.

2. Investigate first, then clarify only the gaps

This is the core of the skill. Prefer reading the code over interrogating the user — don't ask about anything you can find yourself.

• Investigate the codebase to ground the issue. Use the search tools (or dispatch an Explore subagent for a broad "where does X live" question) over config.paths.source:
  • Bug: locate the likely code path, the specific file(s)/function(s) involved, and how it reproduces. Read enough to state a plausible root cause (hedged — "likely in X:42 where …") without committing to a fix.
  • Feature: find where it would plug in, the existing patterns it should follow, and the modules it touches. Note prior art in the repo.
  • Collect concrete file:line / symbol pointers as you go — these are what make the issue buildable.
• Ask targeted clarifying questions (via AskUserQuestion) only for what investigation can't resolve: genuinely ambiguous scope, a missing repro you can't reconstruct, unclear acceptance criteria, or several plausible interpretations. Ask the minimum. If the code answered it, don't ask.

3. Draft the issue

Write a draft the pipeline can build from. Match the repo's issue conventions/templates if it has them. Aim for this shape (trim sections that don't apply):

## Problem / motivation
<what's wrong or missing, and why it matters — 1–3 sentences>

## Repro (bugs)
<steps · expected vs actual>

## Acceptance criteria
- [ ] <observable, checkable outcome>
- [ ] <…>

## Pointers
- `path/to/file.ext:42` — <what lives here / why it's relevant>
- <symbol / module the implementer should start from>

## Scope
In: <the single coherent unit this issue covers>
Out: <explicitly deferred, to keep it buildable>

Keep it a single buildable unit. If the request is really several things or an epic, say so and either (a) propose splitting into separate issues, or (b) file it as an epic labeled to be excluded from auto-dev (config.autoDev.excludedLabels) so the pipeline doesn't try to one-shot it. A tight, well-bounded issue is the whole point — resist the urge to pad scope.

Don't over-prescribe the implementation: give pointers and criteria, not a full diff. The plan step (auto-dev, or a human) decides how.

4. Dedup, then confirm before filing

gh issue list --repo <config.repo> --state open --search "<key terms>" --json number,title,url --limit 30

If an open issue already covers this, surface it and ask whether to add a comment there instead of filing a duplicate.

Then show the user the full draft (title + body + intended labels) and get confirmation — filing a GitHub issue is outward-facing; never create it silently. Let them edit first.

5. File and label

gh issue create --repo <config.repo> --title "<title>" --body "<body>" --label "<labels>"

Labeling:

• Apply an appropriate type label if the repo uses them (bug, enhancement, …) — only ones that already exist; don't invent labels.
• When config.autoDev.enabled: a well-formed, buildable issue should be left unlabeled by state so auto-dev's own triage evaluates it fresh and runs the plan-approval handshake — do not stamp auto:ready by default (that would skip planning). Only apply a config.autoDev.stateLabels.* value if the user explicitly wants to fast-track. For a non-buildable request (epic, question, needs-a-human-decision), apply a config.autoDev.excludedLabels value so the pipeline skips it.
• When auto-dev is disabled/absent: just the type label; no auto:* labels.

6. Report

Give the user the issue number + URL, its labels, and its pipeline status: "ready for auto-dev triage" / "filed as epic, excluded from auto-dev — suggest splitting into #… " / "duplicate of #… , commented there instead."

What makes an issue "ready for the pipeline"

A checklist to hold the draft against before filing:

• A reader (or an autonomous builder) knows what to change and how to tell when it's done — problem is clear, acceptance criteria are observable and checkable.
• It's grounded in the actual code — concrete file/symbol pointers, not just a restatement of the user's words.
• It's a single coherent unit of work, with out-of-scope called out.
• It's not an epic, a question, or a "figure out what we want" — those get excluded or split.

What not to do

• Don't file without confirmation. Show the draft; the issue is outward-facing.
• Don't interrogate the user for things the code answers — investigate first, ask only the gaps.
• Don't stamp auto:ready by default — let auto-dev triage and the plan-approval handshake do their job; fast-track only on explicit request.
• Don't feed an epic to the pipeline. Split it, or file it excluded.
• Don't invent labels — use only ones that exist in the repo.
• Don't over-specify the implementation — pointers and criteria, not a prescribed diff.
• Don't file a duplicate — dedup against open issues first.