Issuing

File issues that read as specs

An issue states what must become true, so a later plan can be written against it. The enemy is the story issue: the occasion that prompted it, a quote from the prompt, and a background paragraph repeating the labels, type and parent that GitHub already shows beside the body. The overcorrection is the one-line issue that never says when it is done, which pushes the whole spec into the plan. An issue is a spec before a plan; a plan reads it and never depends on it staying open.

Invoking this skill authorizes creating the issues it showed you and you approved, with their labels, type, project fields, relations and milestone, and creating the default labels references/fields.md names when the repository defines none of its own. It never closes an issue, never deletes one, and never edits an existing one, except to add a relation to a parent or a blocker you named.

Steps

1. Intake. Turn the request into one goal sentence per issue, and say which sentence came from which part of the request. An issue whose goal sentence needs an "and" for two unrelated outcomes is too big: propose a parent plus sub-issues and ask once, listing the split you would make. Never invent an issue the request does not ask for.

2. Read the repository, invent nothing. Read its labels, issue types, milestones, project fields and issue templates, and pick the vocabulary, as references/fields.md says. Read the language of the last five issues with gh issue list --limit 5 --json title,body --jq '[.[].title]'.

3. Ground the references. Send the exo:explorer agent the paths and symbols the goal sentences name, so References carries real paths. Skip this step for an issue that names no code.

4. Show the draft, then ask once. Print, per issue: the title, the body, and one metadata line holding labels, type, parent, blocked-by, milestone and project fields. Ask one approval question covering all of them. Create nothing before the yes.

5. Create in dependency order. A parent before its children, a blocker before what it blocks, with the commands and field settings in references/fields.md.

6. Read back. gh issue view <n> --json number,title,labels,milestone,url per created issue, and report the URLs, plus everything Step 2 said this repository does not define.

The body

Write it in the language of the existing issues. When there are none, follow the language of the recent pull requests and commits (gh pr list --limit 5 --json title --jq '[.[].title]', git log -5 --format=%s). The skill's own text stays English.

Take the shape from references/fields.md: Spec for a brief or for feature work, Report for a bug, a regression, a chore or a documentation fix. That file holds both section lists, the ban on a background section and on repeating the metadata, and how priority, size and estimate are read off the body; no field and no section is decided here.

References

Judgment

• Explicit user instructions outrank this skill, including a body section it forbids: say once that the metadata already shows it, then write it.
• The repository's vocabulary outranks the request's wording: a label the user names that does not exist is reported, not created.
• A request to change or close an existing issue leaves this skill: report it and let the user run the gh command, except the parent or blocker relation the authorization above covers.
• Sizing belongs to the user. Propose a split once; a repeated request for one issue is the decision.