create-issue

name	create-issue
description	Create one repository-grounded, implementation-ready GitHub issue from a request or clarified plan.

Codex invocation: use $create-issue or select this skill through /skills. References below to /create-issue describe the source repository command.

Use this command when the user wants to turn a product idea, bug, improvement, feature, refactor, technical task, or existing plan into a GitHub issue for the current repository.

The expected result is exactly one confirmed GitHub issue by default, created with the matching GitHub issue template and grounded in user clarification plus repository analysis. Multiple issues are in scope only when the user explicitly requests that change during the interview.

Input

This command expects /create-issue <request>.

<request> can be an incomplete idea, need, bug, improvement, feature, refactor, technical task, product request, or clear existing plan.

If no arguments are provided, look for a sufficiently clear plan or issue scope in the current conversation. If no usable request or plan exists, ask the user what issue they want to create and stop.

Preconditions

Before creating the issue, verify that the current GitHub repository can be identified, at least one GitHub issue creation integration is available, and the repository issue templates can be read.

Use the repository issue templates as the required issue body format:

• .github/ISSUE_TEMPLATE/bug.yml for confirmed or suspected bugs;
• .github/ISSUE_TEMPLATE/feature.yml for new functionality, improvements, refactors, product tasks, and technical tasks that are not bug fixes.

Use the most direct reliable integration available in this order:

• GitHub MCP issue tool when repository identity is clear;
• GitHub CLI gh when MCP is unavailable or unsuitable;
• another configured GitHub integration only when it is the most reliable available option.

If the repository or issue creation integration cannot be determined, report what is missing and stop before drafting commands that may target the wrong repository.

Workflow

1. Determine the initial issue request from $ARGUMENTS or from a clear plan in the current conversation.
2. Analyze the request as a product specification, not as a checklist.
3. Identify only ambiguities that affect product behavior, UX, business rules, edge cases, scope, acceptance criteria, or final GitHub issue content.
4. Ask one clarification question at a time. Each question must resolve one concrete ambiguity.
5. After each user answer, re-evaluate the full specification and continue asking one question at a time until the important behavior branches are clear.
6. Focus the interview on expected behavior, user value, UX, domain rules, edge cases, out-of-scope boundaries, validation, and fit with existing app behavior.
7. Ask about internal technical details only when they affect product behavior, architecture, issue scope, safety, or implementation feasibility.
8. If the request contains multiple independent issues, explain the split and ask whether to reduce scope to one issue, choose one part, cancel, or explicitly create multiple issues. Continue with exactly one issue unless the user confirms otherwise.
9. Classify the request as bug or feature. If the classification is ambiguous and changes the issue template or required fields, ask one clarification question before continuing.
10. Read the selected GitHub issue template and use its fields, labels, title prefix, and required sections as the issue body format.
11. When product scope is clear, inspect the repository before drafting the issue. Use targeted reads and searches over relevant docs, modules, features, tests, architecture boundaries, stores, routes, APIs, components, services, repositories, use cases, entities, value objects, and conventions.
12. Infer likely implementation impact from repository evidence. Explain how each relevant part of the system is likely affected, including product behavior, UI/UX, domain or business rules, main-process/application layers, persistence, IPC/API/integration contracts, renderer state or components, tests, and documentation.
13. Recommend an approach that fits existing patterns without forcing a closed solution when more than one valid implementation path exists.
14. If repository analysis reveals a technical decision that materially changes product behavior, architecture, risk, or scope, ask the user for confirmation before drafting the issue.
15. Decide documentation impact using AGENTS.md, docs/how-to/documentation-writing-standards.md, and docs/how-to/documentation-folder-structure.md before drafting the issue.
16. Do not mark documentation as unnecessary when the issue changes user-visible behavior, local persistence, setup, workflows, architecture, IPC/API contracts, test strategy, tooling, or reusable implementation guidance that is missing, wrong, or ambiguous in docs/**.
17. For bug fixes, write the documentation requirement as a correction of current expected behavior or reusable rule. Do not ask for changelog-style text saying the bug was fixed.
18. For features and infrastructure changes, write the documentation requirement as the expected product behavior, technical rule, workflow, or persistence/setup contract that must be true after implementation.
19. Draft the issue by filling the selected template with the collected product context and technical analysis. Preserve the template's intent and required fields instead of inventing a separate structure.
20. Make the testing strategy specific to the change. Include only applicable unit, integration, component, e2e, and regression tests, with concrete cases for each relevant type and expected behavior contract IDs or documentation gaps. For UI component and E2E cases, specify the user actions to perform and the complete user-visible outcomes to assert. For rich interactions such as charts, include every affected visible dimension in the acceptance test plan, such as all affected axes, mode state, cursor/tooltip output, reset controls, synchronized followers, or rendered geometry. Do not plan tests around internal state mutation or private runtime APIs unless a blocker makes that exception necessary.
21. Include documentation impact in the template fields: docs already consulted, docs likely to update, and whether new product, technical, testing, troubleshooting, or decision documentation is needed.
22. If no docs are required, name the exact existing document section that already covers the expected behavior or explain why the change has no product, technical, workflow, template, or deferred-debt impact.
23. Before creating the issue, show the user a concise final summary and ask for confirmation.
24. Include in the confirmation summary the selected template, title, objective, scope, main acceptance criteria, important decisions from the interview, recommended technical approach, likely affected code areas, documentation to consult or update, testing strategy, and main risks.
25. If the user requests changes, update the specification or continue the interview before asking for confirmation again.
26. After confirmation, create the issue in the current GitHub repository using the selected integration and the selected template format.
27. Keep execution limited to issue creation, then stop and report the result.

Required output

Report:

• command result status;
• GitHub repository used;
• selected issue template;
• issue title;
• issue number and URL;
• whether one issue or multiple issues were explicitly requested and created;
• main product decisions clarified during the interview;
• main repository references used to ground the issue;
• documentation impact decision, including documents to update or exact existing coverage when no update is required;
• behavior contract IDs or missing documentation decisions captured in the issue;
• recommended implementation areas and testing strategy included in the issue.