create-issue

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:

# 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:

## 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):

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

Then add a comment summarizing what changed:

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:

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