---
name: create-issue
description: Turn a problem into a clear GitHub issue that the next-issue worker can claim. Use when the user wants to write, file or create an issue, or asks for a change to the code of a repository that has `.next-issue/config.json`. In that case, file an issue with this skill instead of editing files.
---

# Create an issue

Turn the problem of the user into one GitHub issue, or a split of linked issues when the change is too big for one commit, in the format of `template.md`, next to this file.

Run any next-issue command as `npx -y next-issue@latest <command>`. Never run it from the `PATH`, a global install or a local build.

1. Understand the problem. Restate it in your own words.
2. Find the repository, `<repo>`, that the worker reads. `<remote>` is the value of `remote` in `.next-issue/config.json` at the root of the repository. When there is no config file or no `remote` field, `<remote>` is `origin`. Run `git remote get-url <remote>` and take `<owner>/<name>` from the url, without `.git`. That is `<repo>`. When the host of the url is not `github.com`, `<repo>` is `<host>/<owner>/<name>`, so gh acts on that host. For an ssh url, such as `git@<host>:<owner>/<name>.git`, run `ssh -G <host>` and take the host from its `hostname` line, since `<host>` may be an alias from the ssh config. The host `ssh.github.com` means `github.com` (GitHub's ssh over port 443), so `<repo>` is then `<owner>/<name>`. Pass `--repo <repo>` to every `gh` command, since gh otherwise may pick another remote, such as `upstream`.

   Investigate the code when the problem touches it. Read the relevant files and note what you find, with file paths. Run `gh issue list --repo <repo>` and note each open issue that must be done first, including the issues you create in the same session.

3. Judge whether the change fits one atomic commit that leaves the trunk green. When it does not, propose a split into issues that each land alone and keep the trunk green, in the order they land, and note which issues of the split each one depends on.
4. Ask numbered questions about anything that is unclear: the scope, the expected behaviour, the acceptance criteria. When you propose a split, ask the user to confirm the split with the other questions. Label options with letters and recommend one. Ask again until no question is open.
5. List every choice the implementer would have to make, for example the approach, where data comes from, what to delete and which files to change. Ask the user about each choice that has more than one reasonable answer, with lettered options and a recommended one. Ask these with the questions of step 4.
6. Write the body from `template.md` into a temporary file. Keep every heading of the template and its order. Write each answered choice in `Decisions`. Leave `Decisions` empty when no choice needed asking. Leave `Open questions` empty.
7. Find the ready label, `<ready>`: the value of `labels.ready` in `.next-issue/config.json` at the root of the repository. The worker claims only issues with that label. When `labels.ready` is not set, or there is no config file, `<ready>` is `status:todo`.

   Create the `<ready>` label when the repository does not have it:

   ```bash
   gh label list --repo <repo> --search "<ready>"
   gh label create --repo <repo> "<ready>"
   ```

   When `labels.ready` is empty (`""`), add no label, since the worker then claims every open issue. Skip the label commands.

   Then create the issue without showing the body first, and without a label. Pass every blocker with `--blocked-by`, so the issue carries its blocker links from the moment it exists and no run can claim it before its blockers, whatever `labels.ready` is:

   ```bash
   gh issue create --repo <repo> --title "<title>" --body-file <file> --blocked-by <blockers>
   ```

   `<blockers>` is the comma-separated list of the numbers of the issues it depends on. Leave out `--blocked-by <blockers>` when the issue has no blocker. When gh does not know `--blocked-by` (it needs GitHub CLI 2.94.0 or later), do not create the issue: ask the user to upgrade gh.

8. Only once the issue exists with every blocker linked, add the ready label, unless `labels.ready` is empty. Add no label other than `<ready>`:

   ```bash
   gh issue edit --repo <repo> <number> --add-label "<ready>"
   ```

   For a confirmed split, repeat steps 6 to 8 for each issue of the split, in order. Create each one with `--blocked-by` the issues of the split it depends on, so it is linked before you add its ready label.

9. Once the issue exists with its ready label, or the last issue of a split has its ready label, run `npx -y next-issue@latest status` once. When `labels.ready` is empty, run it too, since the worker claims every open issue.

   When the first line of the status starts with `stopping`, run no `start`: the run is stopping, so the issue waits for the next run. Otherwise run `npx -y next-issue@latest start` once. It starts a run when none is going, and joins a going run.

   Then give the user the issue url, or each url of a split, and the outcome of `start`, or that the run is stopping, in one line, and stop.

10. When the user asks for a change to the issue, make the change on GitHub. Write the new body into the temporary file and run:

    ```bash
    gh issue edit --repo <repo> <number> --body-file <file>
    ```

    To change the title, run:

    ```bash
    gh issue edit --repo <repo> <number> --title "<title>"
    ```

Once the issue exists, do not implement it in this session. The next-issue worker does the work.

## Sections

- Problem: what is wrong or missing, and who it affects.
- Context and findings: what you found in the code and the docs, with paths.
- Decisions: each choice the user made about how to do the change, with the chosen option. Empty when no choice needed asking.
- Acceptance criteria: a list of checks that show the issue is done, each one observable. Name each concrete target, such as each file, test or item, instead of a count or a general phrase like "update the docs". Write each check as a plain bullet (`- `), not a task-list checkbox (`- [ ]`), since nothing ticks the boxes.
- Out of scope: what the issue does not cover.
- Open questions: empty when the issue is created.
