mgratzer/forge/forge-create-issue

Create Issue

Collaboratively plan and create well-structured Issues through interactive discussion. The Issue is created in the project's Issue tracker — see issue-operations for provider detection.

Input

The Issue idea or problem description: $ARGUMENTS

Optional: -- <additional context> for execution guidance.

If no argument is provided, ask the user what they'd like to create an Issue for.

Process

Step 1: Research the Codebase

Parse the user's input, then explore the relevant code before asking anything:

• Find related existing implementations and patterns
• Identify integration points and potential reuse

Verify external dependencies are accessible if relevant — flag broken ones before proceeding.

Step 2: Clarify

Use AskUserQuestion to gather what the code can't answer:

• Problem context — what triggered this, who's affected, current vs desired behavior
• Success criteria — how will we know this is done
• Constraints — technical limitations, dependencies

Step 3: Present Alternative Approaches

Skip this step if the input already contains a chosen approach with rationale — the decision was already made through deliberate analysis. Proceed directly to Step 4.

Otherwise, present the structurally distinct approaches you found — usually two to four — rather than a single recommendation; the choice belongs to the user.

For each approach:

• One-line summary
• How it works (brief)
• Pros and cons
• Relative complexity (Low / Medium / High)
• Key files affected

Let the user choose or combine approaches via AskUserQuestion.

Step 4: Assess Scope

Evaluate if this should be one Issue or multiple.

Split when: distinct deliverables, different codebase areas, parallelizable work, or effort exceeds 1-2 days.

Keep together when: tightly coupled changes or splitting adds coordination overhead.

When splitting, slice vertically — each Issue is a thin end-to-end path (see vertical-slicing). Classify each as AFK or HITL (see afk-vs-hitl.md). Order by dependency, and note which Issues each one is blocked by. A forge-shape breakdown arrives sliced, classified, and ordered: check it against the same rules and re-slice only a horizontal Issue.

If splitting makes sense, offer: an epic with sub-issues (the default for several Issues), linked Issues without a parent, or a single Issue.

Step 5: Draft the Issue

Title: Use conventional commit format — <type>(<scope>): <description>

Labels: Discover what labels exist before applying any — see issue-operations. Apply at least one type label and relevant area labels.

Body structure:

## Summary
[1-2 sentences]
 
**Execution mode:** [AFK | HITL] <!-- markdown provider: use the `mode` frontmatter field instead -->
 
## Problem / Motivation
[Why this needs to exist]
 
## Proposed Solution
[Chosen approach with implementation details]
 
### Alternatives Considered
[Other approaches and why they weren't chosen]
 
### Implementation Constraints
[When applicable: preferred libraries, config locations, patterns to follow, external dependencies]
 
## Acceptance Criteria
-[ ] [Specific, testable criteria]
-[ ] Tests added/updated
-[ ] Documentation updated (if applicable)

When a view explains the Proposed Solution better than prose, include one (see visuals).

Step 6: Review and Create

Present the draft to the user and iterate until satisfied (use AskUserQuestion for approve/revise decisions). Then create the Issue using the project's Issue tracker — see issue-operations for provider-specific mechanics. For several Issues, create them in dependency order, then Link Issues: each sub-issue to its parent, and each Issue to the Issues it is blocked by.

Share the Issue reference. Suggest using forge-implement to start implementation.

Guidelines

• Be curious — challenge assumptions, ask "why" and "what if"
• Don't over-specify — leave room for implementer judgment
• No time estimates in the Issue — the Step 4 effort heuristic is for deciding splits, not for the Issue body

Related Skills

Next step: Use forge-implement to implement the Issue.

Example Usage

/forge-create-issue add dark mode support
/forge-create-issue add dark mode support -- keep it to a single Issue
/forge-create-issue