---
name: create-issues
description: Draft and create GitHub or Linear issues from a spec, files, screenshots, TODOs, or inline text. Use when the user explicitly asks to turn source material into one or more reviewed issues.
---

# Create Issues

Turn source material into focused, reviewed issues in GitHub or Linear. Tracker-specific access, commands, and dependency handling live in [references/github.md](references/github.md) and [references/linear.md](references/linear.md); use the one for the chosen tracker.

## Step 1: Parse the Request

From the current request and any text supplied with the invocation, extract:

1. **Intent** — what kind of issues the user wants (bug, feature, enhancement, etc.) and any labeling or formatting instructions.
2. **Source material** — a spec, file, folder, image, or inline content. Verify any referenced paths exist before proceeding.
3. **Tracker** — the one the user names. Otherwise infer it from the source (a GitHub or Linear issue link), project instructions such as `AGENTS.md` or `CLAUDE.md`, or which tracker is reachable; ask if both are plausible. Prefer an available connector or MCP server, otherwise the tracker's CLI.

## Step 2: Extract Issue Content

Pull out distinct issues from the source material (one per concern). Apply the user's instructions consistently across all items.

| Source type | How to extract |
|-------------|----------------|
| Spec or plan (e.g. `project_spec.md`, `feature_spec_<name>.md`) | Split it into vertical slices: each delivers user-visible or testable behavior and fits one build session. Follow the spec's milestones; if the MVP is being built straight from the spec, only the later milestones become issues unless the user says otherwise. If the whole spec fits one build session, one issue is fine. Carry each slice's acceptance criteria and verification forward, and record the order as dependencies. |
| Inline text in the prompt | Parse for distinct items (numbered lists, bullets, clearly separate concerns) |
| Markdown or text file | Read the file; split on headers, lists, or clear section breaks |
| Image / screenshot | Analyze the image and transcribe relevant evidence; use a repository-relative reference only when readers can access it |
| Folder | Enumerate candidate files first; exclude `.git`, dependencies, build output, hidden secret files, binaries, and symlinks that escape the requested folder. Ask only if it's unclear which files the user meant. |
| Code files (TODO/FIXME scans) | Search for the pattern, consolidate matches about the same concern, and include repository-relative paths and verified line numbers |

## Step 3: Structure Each Issue

### Title
- **Preserve the user's original wording** from the source material. Do not rephrase, summarize, or "action-verb-ify" titles unless the user explicitly asks for that.
- If the source has clear item names (e.g., "Transcript selector: List all .txt files"), use those directly as the issue title.
- Only lightly format if needed (e.g., capitalization, removing markdown artifacts).
- For a slice of a spec, or source content with no clear title, write a short title naming the outcome (e.g., "Export expenses as CSV"); section headings like "Milestone 1" are not titles.

### Body
Format the body using [references/issue_body_template.md](references/issue_body_template.md). Fill in the sections that apply; omit any that aren't relevant.

### Labels
Use [references/labels.md](references/labels.md) for the label taxonomy, selection rules, and auto-detection keywords. Pick the most specific label that fits each issue. Issues can have multiple labels when appropriate.

## Step 4: Resolve Destination, Duplicates, and Labels

1. Resolve the exact destination (a GitHub repository, or a Linear team and optional project) and who can see it, and use it explicitly for every read and write. Do not rely on the current directory for a mutation.
2. Search both open and closed issues for likely title or content duplicates. Surface matches before proposing a new issue.
3. Fetch the complete label inventory. Apply only labels that exist unless the user explicitly approves creating the exact missing labels.
4. Scan outgoing content for secrets, private code, personal data, machine-local paths, and unrelated material. Redact or omit it before review.
5. Link a source spec by its URL in the project's GitHub repository (e.g. `https://github.com/OWNER/REPO/blob/<default-branch>/plans/feature_spec_<name>.md`), not a local path. If the spec isn't committed and pushed yet, say so in the preview and offer to commit and push it first. Either way, write each issue body so it can be worked on without opening the spec.
6. A local screenshot path is not an attachment issue readers can access; upload an image only through a verified supported workflow and with user approval.

## Step 5: Preview

Before creating anything, show the user the exact destination and who can see it, the number of issues, each issue's exact title, body, labels, and dependencies with any likely duplicate, and any missing labels you propose to create. For a large batch, write the payload to a local draft file rather than truncating it.

If the user asked you to *create* the issues, this preview is informational: publish once it's shown, and don't ask again for a payload they already approved. If they asked for drafts or a review, or the destination or what should be disclosed is unclear, wait for their go-ahead.

## Step 6: Create Issues

Create only the missing labels included in the approved preview, then create the issues in dependency order so blockers exist before the issues that depend on them. Record each dependency with the tracker's own mechanism.

After each issue is created, record its identifier and URL immediately and read back the title, body, labels, and dependencies. Stop on ambiguous failures, recheck for duplicates before retrying, and report partial completion.

## Step 7: Summary

After all issues are created, provide a summary:
- Total issues created, with identifiers, titles, and links
- The dependency order, when there is one
- Anything not created, and why

## Guidelines

- Keep issues focused and atomic - one concern per issue
- Write from the perspective of "what needs to be done"
- Include enough context for someone else to understand and work on the issue
- Prove success end to end: give each issue that completes a user journey an end-to-end check through the real user path (no test-only shortcuts), say how an agent drives it (browser, terminal, HTTP calls), and name the side effects to confirm, such as saved records, files written, or messages sent
- A label the user names wins over keyword hints. **Infer intent** when none is named: "fix the issues in..." implies bugs; "add features from..." implies enhancements

## Error Handling

- If neither a connector nor an authenticated CLI for the tracker is available, say so and hand back the drafts
- If an image can't be read, note this and ask for alternative input