Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
71 changes: 71 additions & 0 deletions .agents/skills/create-issue/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,71 @@
---
name: create-issue
description: Create a GitHub issue in this repository from its issue forms (Feature / improvement, Bug report), with checkable "Done when" criteria. Use when the user asks to create, raise, open or file an issue, report a bug, or turn an idea, note, Miro sticky or conversation into a ticket. Not for pull requests or for editing an existing issue.
---

# Create an issue

Create an issue that looks exactly like one filed through the repository's issue forms in the browser. The forms in `.github/ISSUE_TEMPLATE/` are the source of truth: read them every time, never rely on a remembered list of fields.

Run every command from the repository root. You need `gh` (authenticated) and `uv`.

## 1. Read the forms

```bash
uv run .agents/skills/create-issue/scripts/render_issue.py list
```

This prints each template's name, title prefix, labels and fields (label, type, required, description, default value, options).

Pick the template that fits: a **Bug report** for something that isn't working, a **Feature / improvement** for new work. If the request fits neither, or you can't tell, ask the user.

## 2. Search for duplicates

```bash
gh issue list --state all --search "<two or three key words>" --limit 10
```

If a close match exists, show it to the user and ask whether to comment on it instead. Only tick the form's "I have searched the existing issues" box after you have actually searched.

## 3. Draft the answers

Fill each field from what the user said and from the conversation. Follow each field's description from step 1.

- **Title**: short and specific, without the template prefix (the script adds it).
- **Context / bug fields**: the user's facts, not your guesses. Link the source (Miro sticky, decisions doc, meeting notes, failing run) when there is one.
- **Done when**: keep the template's default structure (**Must have** / **Nice to have**). Propose concrete criteria drawn from the conversation, each one checkable by someone else without asking. Never present invented criteria as agreed: the user confirms or edits them in step 4.
- Leave optional fields empty rather than padding them; they render as `_No response_`, as on GitHub.
- Never put credentials, tokens or personal data in an issue.

Write the answers to a temporary file outside the repository, keyed by field label, with checkbox fields as a list of the options to tick:

```json
{
"title": "Short summary",
"Is there an existing issue for this?": ["I have searched the existing issues"],
"Context": "...",
"Done when": "**Must have**\n\n- [ ] ...\n\n**Nice to have**\n\n- [ ] ..."
}
```

Render it:

```bash
uv run .agents/skills/create-issue/scripts/render_issue.py render <template> <answers.json> <tmp-dir>
```

The script checks required fields and unknown labels, writes `body.md`, and prints the final `title`, `labels` and `body_file`. Fix and re-render on any error.

## 4. Confirm with the user

Creating an issue is visible to the whole team. Show the user the final title, labels and the full rendered body, and ask them to confirm. Apply any edits and re-render. Do not create the issue without a clear yes.

## 5. Create it

```bash
gh issue create --title "<title>" --body-file <body_file> --label "<label>" [--label "<label>" ...]
```

Pass each label from the render output with its own `--label`. Report the issue URL to the user.

Then offer, without doing it unasked, to create the linked branch so the work can start (`gh issue develop <number> --checkout`).
161 changes: 161 additions & 0 deletions .agents/skills/create-issue/scripts/render_issue.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,161 @@
# /// script
# requires-python = ">=3.10"
# dependencies = ["pyyaml"]
# ///
"""Render a GitHub issue from the repository's issue forms.

`gh issue create` cannot fill an issue form, so this rebuilds what GitHub produces when a form is
submitted in the browser: the form's title prefix, one `### <label>` section per field, and the
form's labels. Fields are read from `.github/ISSUE_TEMPLATE/` at runtime, so template edits need
no change here.

uv run render_issue.py list
uv run render_issue.py render <template> <answers.json> <out-dir>

`answers.json` maps field labels to values, plus a `title` key:

{"title": "Short summary", "Context": "...", "Done when": "**Must have**\\n- [ ] ..."}

Checkbox fields take a list of the option labels to tick. `render` writes `<out-dir>/body.md` and
prints JSON with `title`, `labels` and `body_file` for `gh issue create`.
"""

import json
import subprocess
import sys
from pathlib import Path

import yaml

NO_RESPONSE = "_No response_"


def template_dir() -> Path:
root = subprocess.run(
["git", "rev-parse", "--show-toplevel"],
capture_output=True,
text=True,
check=True,
).stdout.strip()
return Path(root) / ".github" / "ISSUE_TEMPLATE"


def load_forms() -> dict[str, dict]:
forms = {}
for path in sorted(template_dir().glob("*.y*ml")):
form = yaml.safe_load(path.read_text())
if isinstance(form, dict) and "body" in form:
forms[path.stem] = form
return forms


def input_fields(form: dict) -> list[dict]:
"""The fields that appear in the issue body; markdown blocks are display-only."""
return [item for item in form["body"] if item["type"] != "markdown"]


def describe(forms: dict[str, dict]) -> list[dict]:
out = []
for key, form in forms.items():
fields = []
for item in input_fields(form):
attrs = item.get("attributes", {})
field = {
"label": attrs["label"],
"type": item["type"],
"required": item.get("validations", {}).get("required", False),
"description": attrs.get("description", "").strip(),
}
if "value" in attrs:
field["default"] = attrs["value"]
if item["type"] in ("checkboxes", "dropdown"):
field["options"] = [
o["label"] if isinstance(o, dict) else o for o in attrs["options"]
]
if item["type"] == "checkboxes":
field["required"] = any(
isinstance(o, dict) and o.get("required")
for o in attrs["options"]
)
fields.append(field)
out.append(
{
"template": key,
"name": form["name"],
"description": form.get("description", ""),
"title": form.get("title", ""),
"labels": form.get("labels", []),
"fields": fields,
}
)
return out


def render(form: dict, answers: dict) -> tuple[str, str, list[str]]:
title = answers.get("title", "").strip()
if not title:
sys.exit("answers.json needs a non-empty 'title'")
prefix = form.get("title", "")
title = (
prefix.replace("<title>", title) if "<title>" in prefix else f"{prefix}{title}"
)

sections, missing = [], []
for item in input_fields(form):
attrs = item["attributes"]
label = attrs["label"]
value = answers.get(label)
if item["type"] == "checkboxes":
ticked = set(value or [])
options = attrs["options"]
if any(o.get("required") and o["label"] not in ticked for o in options):
missing.append(label)
text = "\n".join(
f"- [{'X' if o['label'] in ticked else ' '}] {o['label']}"
for o in options
)
else:
text = (value or "").strip()
if not text and item.get("validations", {}).get("required"):
missing.append(label)
text = text or NO_RESPONSE
sections.append(f"### {label}\n\n{text}")

unknown = (
set(answers)
- {"title"}
- {i["attributes"]["label"] for i in input_fields(form)}
)
if unknown:
sys.exit(f"unknown fields in answers.json: {sorted(unknown)}")
if missing:
sys.exit(f"required fields missing: {missing}")
return title, "\n\n".join(sections) + "\n", form.get("labels", [])


def main() -> None:
forms = load_forms()
if len(sys.argv) == 2 and sys.argv[1] == "list":
print(json.dumps(describe(forms), indent=2, ensure_ascii=False))
elif len(sys.argv) == 5 and sys.argv[1] == "render":
key, answers_path, out_dir = sys.argv[2:]
if key not in forms:
sys.exit(f"unknown template {key!r}; choose from {sorted(forms)}")
title, body, labels = render(
forms[key], json.loads(Path(answers_path).read_text())
)
body_file = Path(out_dir) / "body.md"
body_file.parent.mkdir(parents=True, exist_ok=True)
body_file.write_text(body)
print(
json.dumps(
{"title": title, "labels": labels, "body_file": str(body_file)},
ensure_ascii=False,
)
)
else:
sys.exit(__doc__)


if __name__ == "__main__":
main()
1 change: 1 addition & 0 deletions .claude/skills/create-issue
73 changes: 73 additions & 0 deletions .github/ISSUE_TEMPLATE/bug_report.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,73 @@
name: 🐞 Bug report
description: Report something that isn't working
title: "[BUG] <title>"
labels: [bug]
body:
- type: checkboxes
attributes:
label: Is there an existing issue for this?
description: Please search to see if an issue already exists for the bug you encountered.
options:
- label: I have searched the existing issues
required: true
- type: textarea
attributes:
label: Current behavior
description: A concise description of what you're experiencing.
validations:
required: true
- type: textarea
attributes:
label: Expected behavior
description: A concise description of what you expected to happen.
validations:
required: true
- type: textarea
attributes:
label: Steps to reproduce
description: Steps to reproduce the behavior.
placeholder: |
1. On this tile / country / commodity...
2. With this config...
3. Run '...'
4. See error...
validations:
required: false
- type: textarea
attributes:
label: Environment
description: Where it happened.
value: |
- Commit / release:
- Run location (local, cluster, …):
- Python:
validations:
required: false
- type: textarea
attributes:
label: Done when
description: The criteria for closing this issue. Must haves block closing; nice to haves can move to a follow-up issue.
value: |
**Must have**
- [ ] Bug no longer reproduces with the steps above
- [ ] Regression test added

**Nice to have**
- [ ]
validations:
required: true
- type: textarea
attributes:
label: Anything else?
description: |
Links? References? Logs?
validations:
required: false
- type: markdown
attributes:
value: |
---
**Tips**
- Write each *Done when* item so anyone can check it without asking you.
- Keep *Must have* short; anything that can wait goes under *Nice to have* or a follow-up issue.
- Attach images or log files by dragging them into any text field.
1 change: 1 addition & 0 deletions .github/ISSUE_TEMPLATE/config.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
blank_issues_enabled: false
51 changes: 51 additions & 0 deletions .github/ISSUE_TEMPLATE/feature_request.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,51 @@
name: ✨ Feature / improvement
description: Propose new work. Raise this before opening a PR.
title: "[Feature] <title>"
labels: [enhancement]
body:
- type: checkboxes
attributes:
label: Is there an existing issue for this?
description: Please search to see if an issue already exists for this work.
options:
- label: I have searched the existing issues
required: true
- type: textarea
attributes:
label: Context
description: What problem does this solve, and why now? Link the source (Miro sticky, decisions doc, meeting notes, …).
validations:
required: true
- type: textarea
attributes:
label: Proposed change
description: What you intend to do. Can stay rough at this stage.
validations:
required: false
- type: textarea
attributes:
label: Done when
description: The criteria for closing this issue. Must haves block closing; nice to haves can move to a follow-up issue.
value: |
**Must have**
- [ ]

**Nice to have**
- [ ]
validations:
required: true
- type: textarea
attributes:
label: Anything else?
description: |
Links? References? Alternatives considered?
validations:
required: false
- type: markdown
attributes:
value: |
---
**Tips**
- Write each *Done when* item so anyone can check it without asking you.
- Keep *Must have* short; anything that can wait goes under *Nice to have* or a follow-up issue.
- Attach images or log files by dragging them into any text field.
Loading
Loading