create-issue

---
name: create-issue
description: This skill should be used when the user asks to "create an issue", "create a GitHub issue", "open an issue", "write up an issue", "file an issue", or after a design has been verified and needs to be captured as a trackable GitHub issue for implementation. Also handles updating an existing issue when an issue number is provided as context.
tools: Read, Glob, Grep, Bash, Edit, AskUserQuestion
---

# Create Issue

Create or update a well-structured GitHub issue from a verified design document. The issue serves as the implementation brief — everything a developer (or Claude) needs to build the feature without ambiguity.

**Announce at start:** If updating an existing issue: "Updating issue #N from the design document." Otherwise: "Creating GitHub issue from the design document."

## When to Use

- After a design document has been written and verified
- When the user wants to track a feature as a GitHub issue
- When transitioning from design to implementation planning
- When an existing issue number is passed as context (update mode — syncs the issue with the design document)

## Process

### Step 1: Assemble design content

Design content for new issues comes from the current conversation context (brainstorming output, inline arguments, or previously gathered decisions) — not from `docs/plans/`.

**Context sources (in priority order):**
1. If `issue` is already set in lifecycle context (the user passed an existing issue number): load the existing issue body via `gh issue view <issue_number> --json body,title --jq '{title, body}'`. This is **update mode** — skip draft assembly and go directly to Step 5.
2. From brainstorming output in the conversation: extract scope, approach, decisions, and acceptance criteria.
3. From inline `start:` args (user description + any explicitly provided context).
4. From any design-document content already written earlier in the session (in conversation context — not from a file).

Assemble a minimal issue body from the gathered context. The body will include an empty design marker block that `feature-flow:design-document` will fill in on the next lifecycle step.

**Design marker block (placeholder — will be replaced by design-document):**
```
<!-- feature-flow:design:start -->
(pending design-document — will be filled in by `feature-flow:design-document`)
<!-- feature-flow:design:end -->
```

### Step 2: Check Repository Context

Gather context for issue creation:

```bash
# Check for existing labels
gh label list --limit 50

# Check for milestones
gh milestone list

# Check recent issues for style/convention
gh issue list --limit 5
```

### Step 3: Determine Issue Structure

Read `references/issue-templates.md` to select the appropriate template for the feature type.

**Check project context:** If `.feature-flow.yml` exists and `platform` is `ios`, `android`, or `cross-platform`, include mobile-specific sections in the issue (Feature Flag Strategy, Rollback Plan, Device Compatibility, Beta Testing Requirements). See `../../references/platforms/mobile.md` for section content.

Map the design document sections to issue sections:

| Design Doc Section | Issue Section |
|-------------------|---------------|
| Overview | Summary (2-3 sentences + concrete example) |
| User Flow | User Flow (numbered steps) |
| Data Model Changes | Data Model Changes (table with columns and types) |
| Pipeline / Architecture | Pipeline Architecture (diagram or description) |
| New Components | New Components (bulleted list) |
| UI Adaptations | UI Adaptations (bulleted list) |
| Migration Requirements | Migration Summary (count + link to design doc) |
| Scope | Key Decisions (bulleted list of what was decided and why) |
| [findings from verification] | Implementation Notes (blockers, gaps, and things to watch for) |

**Not every section is needed.** Include only sections that have substantive content from the design doc.

### Step 4: Draft the Issue

Compose the issue body. Follow these principles:

- **Summarize, don't duplicate:** The issue is a brief, not a copy of the design doc. Include enough to understand the scope without opening the doc.
- **Concrete examples:** Include at least one input/output example in the summary
- **Implementation notes from verification:** If design-verification was run, include its findings as implementation notes
- **Design section placeholder:** Always include the empty design marker block. Design is captured in this issue body under the `## Design (feature-flow)` section (populated by design-document).

**Issue format:**

```markdown
## Summary
[2-3 sentences + concrete example]

## User Flow
1. **[Step name]** — [description]
2. **[Step name]** — [description]
3. **[Step name]** — [description]

## [Technical sections as needed — Data Model, Pipeline, Components, etc.]

## Key Decisions
- [decision and rationale]
- [decision and rationale]

## Implementation Notes
- [blocker or gap from verification]
- [technical consideration]

<!-- feature-flow:design:start -->
(pending design-document — will be filled in by `feature-flow:design-document`)
<!-- feature-flow:design:end -->
```

### Step 5: Add Metadata

Before creating or updating the issue, determine appropriate metadata:

- **Title:** Under 70 characters. Format: `[Feature Name] — [Brief description]`
- **Labels:** Match existing repo labels (e.g., `enhancement`, `bug`, `feature`)
- **Milestone:** If the repo uses milestones and one applies, assign it
- **Assignee:** Only if the user specifies one

Present the draft to the user:

**If updating an existing issue:**
```
Update issue #N:

Title: [title]
Labels: [labels]
Milestone: [if applicable]

[full body]

Update this issue?
```

Use `AskUserQuestion` to confirm. Options:
- "Update as-is" with description: "*Recommended — applies the drafted title, body, and labels to the existing issue immediately*"
- "Let me edit first" with description: "Provide corrections in freeform text — the draft will be revised before updating"
- "Cancel" with description: "Abort — the issue will not be modified"

**YOLO behavior:** If `yolo: true` is in the skill's `ARGUMENTS`, skip this question. Auto-select "Update as-is" and announce: `YOLO: create-issue — Confirm update → Update as-is`

**If creating a new issue:**
```
Issue draft:

Title: [title]
Labels: [labels]
Milestone: [if applicable]

[full body]

Create this issue?
```

Use `AskUserQuestion` to confirm. Options:
- "Create as-is" with description: "*Recommended — creates the issue on GitHub with the drafted title, body, and labels*"
- "Let me edit first" with description: "Provide corrections in freeform text — the draft will be revised before creating"
- "Cancel" with description: "Abort — no issue will be created"

**YOLO behavior:** If `yolo: true` is in the skill's `ARGUMENTS`, skip this question. Auto-select "Create as-is" and announce: `YOLO: create-issue — Confirm create → Create as-is`

### Step 6: Create or Update the Issue

**If updating an existing issue (issue number provided as context):**

```bash
gh issue edit N --title "[title]" --body "$(cat <<'EOF'
[issue body]
EOF
)"
```

Then add a comment summarizing what changed:

```bash
gh issue comment N --body "Updated from design document: [1-line summary of what changed]. Design is captured in this issue body under the ## Design (feature-flow) section (populated by design-document)."
```

**If creating a new issue:**

```bash
gh issue create --title "[title]" --label "[label]" --body "$(cat <<'EOF'
[issue body]
EOF
)"
```

Report the issue URL to the user.

### Step 7: Suggest Next Steps

**If updated:**
```
Issue #N updated: [URL]

Recommended next steps:
1. Run `feature-flow:design-document` to merge the design into this issue body
2. Run `feature-flow:design-verification` to check the design against the codebase
3. Run `superpowers:writing-plans` to create an implementation plan with acceptance criteria
```

**If created:**
```
Issue created: [URL]

Recommended next steps:
1. Run `feature-flow:design-document` to merge the design into this issue body
2. Run `feature-flow:design-verification` to check the design against the codebase
3. Run `superpowers:writing-plans` to create an implementation plan with acceptance criteria
```

## Quality Rules

- **No orphan decisions:** Every key decision from the design doc should appear in the issue (in Key Decisions or as context in other sections)
- **Accurate counts:** Migration counts, component counts, and phase counts must match the design doc exactly
- **Design in issue body:** Design is captured in this issue body under the `## Design (feature-flow)` section (populated by design-document). Always include the empty design marker block so `feature-flow:design-document` can fill it in.
- **Consistent terminology:** Use the same names for tables, columns, components, and concepts as the design doc and codebase
- **Stand-alone readability:** A developer reading only the issue (without the design doc) should understand what to build, even if they need the doc for implementation details

## Additional Resources

### Reference Files

For issue templates across different feature types:
- **`references/issue-templates.md`** — Templates and examples for different issue types (new feature, API integration, UI feature, data migration, refactor)

For platform-specific issue sections:
- **`../../references/platforms/mobile.md`** — Mobile-specific sections: Feature Flag Strategy, Rollback Plan, API Versioning, Beta Testing Requirements

• SKILL.md 9 KB
• references/issue-templates.md 6 KB