create-issue

name	create-issue
description	Use when you have a rough user story, bug report, or feature idea that needs to become a well-structured GitHub issue.
argument-hint	<user-story>

Prerequisites

If $ARGUMENTS is empty, ask the user to describe their user story, bug report, or feature idea before proceeding.

Steps

Step 1: Document current state

Invoke the /docs-verify skill with the topic extracted from the user story (e.g., /docs-verify survey module).

This will verify and update documentation in docs/internal/ for the relevant features.

After the skill completes, commit and push the documentation changes.

Step 2: Clarify user story

Evaluate whether the user story needs clarification based on the doc findings and the story itself.

General principle: Identify gaps, ambiguities, or risks that would produce a weak or incorrect GitHub issue. If the story is clear and the feature is straightforward, skip to Step 3.

Ask when:

• User story is missing who benefits or why it's needed
• No clear scope boundary — could mean several different things
• Doc review revealed the feature touches multiple modules or has non-obvious dependencies
• Acceptance criteria are implied but not stated, and there are multiple valid interpretations
• Tension between what was asked and what the codebase currently supports

Skip when:

• Bug report with clear repro steps
• Small feature with obvious scope ("add a tooltip to the X button")
• User story already specifies behavior, scope, and edge cases

If clarification is needed:

• Ask questions one at a time
• Prefer multiple choice when the options are known
• Bias toward brevity — only ask what genuinely reduces ambiguity
• If the user says "just create it" or similar, stop and proceed to Step 3

Record all Q&A pairs for the handoff:

## Clarifications
Q: [question asked]
A: [user's answer]

Step 3: Create GitHub issue

Use the devflow:github-issue-creator subagent to create a well-structured GitHub issue. Do not add labels to the created issue.

Pass to devflow:github-issue-creator:

• The original user story (below)
• The documentation findings from Step 1 (file paths and summary of current state)
• Any gaps between current implementation and what the user story requires
• Clarifications from Step 2 (structured Q&A pairs, appended after documentation findings). Omit this section if no questions were asked.

---

User Story (rough draft): $ARGUMENTS