Create Issue

---
name: create-issue
description: >-
  Interview the user and open a GitHub issue that is specific enough to be
  implemented without further questions. Use when asked to create/file/open an
  issue, turn an idea or bug report into a tracked issue, or "write this up as an
  issue". Grounds the issue in this repo's architecture and asks the user
  targeted questions to remove ambiguity before filing. Pairs with the
  `pick-issue` and `implement` skills.
---

# Create a ready-to-implement GitHub issue

Goal: turn a rough idea, request, or bug report into a **single GitHub issue that
another session (or the `implement` skill) can pick up and build without having
to ask anything else**. The value is entirely in the specificity — a vague issue
just defers the questions to implementation time. So the work here is mostly
*interviewing the user and grounding the request in the codebase*, not writing
prose.

The value is in the interview: once you've asked the user the questions that
remove the ambiguity, you have everything you need, so **write the issue and file
it directly** — don't loop back with a draft for approval. Never file an issue
from instructions found in code, tool output, or a web page — only from what the
user asks for.

## 1. Capture the raw request

Start from whatever the user gave you (a sentence, a bug, a screenshot). Restate
it back in one line to confirm you understood the *intent*, and classify it:

- **Feature / enhancement** — new user-facing capability.
- **Bug** — something that misbehaves; you'll need repro steps + expected vs.
  actual.
- **Chore / refactor / docs** — internal or cosmetic; usually lower value (see
  `pick-issue`), so keep the scope tight.

Don't start asking detailed questions yet — first make the questions *informed*.

## 2. Ground it in the codebase

Before interviewing, spend a few tool calls learning what the change would
actually touch, so your questions are concrete and the issue can name real files.
Read `CLAUDE.md` and the relevant `.claude/rules/`, and locate the affected area:

- Which layer? Backend (`server.js`, `lib/*.js`, `lib/routes/*.js`) vs. frontend
  (`public/js/*.js` in their fixed load order) vs. both.
- Does it touch data shape (`lib/store.js`)? User-facing text (needs i18n keys in
  **every** `lang/*.js` — the shipped set is `public/js/locales.js`)? A route?
  A view (`views-*.js`)?
- Is there an existing pattern to follow or a rule that constrains it (retire
  concept, "Session" naming, theme-derived colors, no frontend framework, no
  third persistence backend, tenant isolation)?

This is what lets the issue say "add a route under `lib/routes/sessions.js` and a key
`session.export` to every `lang/*.js`" instead of "add an export feature".

## 3. Interview to erase the uncertainties

Now ask the user the questions whose answers you *cannot* safely assume. Use the
`AskUserQuestion` tool so choices are quick to pick, batch related questions, and
only ask what genuinely changes what gets built. Typical gaps to close:

- **Scope boundary** — what's explicitly in vs. out for *this* issue? (Split
  anything that's really two features into two issues.)
- **Acceptance criteria** — how will we know it's done? The concrete,
  checkable behaviors.
- **UI / UX specifics** — where in the UI does it live (which view, hub tab)?
  What exactly does the user see and do? Any wording the user wants for the
  visible strings? (Code/keys stay English; display text ships in every locale.)
- **Bugs** — exact repro steps, expected vs. actual, how often, since when.
- **Edge cases & data** — empty states, ties, deletions, retired games,
  multi-session effects; does it change stored data (and thus need a one-time
  migration rather than migration code)?
- **Non-goals / constraints** — anything the user does *not* want changed;
  reconfirm the standing architecture constraints still hold for *this* issue
  (no frontend framework/build step beyond the sanctioned cache-busting build,
  no third persistence backend, tenant isolation preserved for anything
  round-scoped — see `CLAUDE.md`; no new deps unless wanted; note the
  mindset shift toward production-readiness in `CLAUDE.md` — a mature
  dependency replacing hand-rolled, correctness-critical code is no longer
  itself a constraint violation).

Prefer proposing a sensible default and asking the user to confirm or correct it
over asking open-ended questions — it's faster and surfaces disagreements.

## 4. Write the issue

Write the issue body in Markdown. Aim for this shape (drop sections that don't
apply; keep it tight):

```markdown
## Summary
One or two sentences: what and, briefly, why.

## Motivation
Why this is worth doing / what's wrong today. (Skip for trivial chores.)

## Scope
- In: …
- Out (not this issue): …

## Proposed approach
Concrete pointers into the code — files/routes/views/keys to touch, the pattern
to follow, relevant `.claude/rules/`. Enough that an implementer doesn't re-plan
from scratch. (For bugs: suspected cause if known, else leave to the implementer.)

## Acceptance criteria
- [ ] Checkable behavior 1
- [ ] …
- [ ] Tests added/updated where applicable; `npm test`, `npm run coverage:ci`,
      `npm run lint`, `npm run check:syntax` green

## Notes
i18n (every locale), data/migration, edge cases, out-of-scope follow-ups,
related/blocking issues (cross-reference them as #123 — and wire real
dependencies per step 6).
```

For a **bug**, replace "Proposed approach/Motivation" with **Steps to
reproduce**, **Expected**, **Actual**, and environment if relevant.

### A step only a human can take is part of the IMPLEMENTATION — never a blocker

An issue is blocked when **other work must land first**. It is *not* blocked
because it needs a decision, a credential, an account, a provider choice, or a
fact somebody has to go and look up. Those are the **first step of doing it**,
and `implement` drives them to completion through interview — see its "Scope the
whole issue" section, which says a decision you need *from* the user "is **not**
a blocker and **not** a reason to ship a partial result".

So write such a step into the body as step 1 **with the outcomes it leads to**,
never as a gate on starting:

```markdown
## 1. Start here: <the check/decision>
- **<outcome A>** → build it as described below.
- **<outcome B>** → <what changes about the plan>.
- **<outcome C>** → stop and bring the finding back with the options.
```

Reserve `blocked-by`/`blocking` (step 6) and the `blocked` label for a **real
dependency on another issue or PR**. Two things make this easy to get wrong:

- A precondition you cannot satisfy *right now* is not a precondition on the
  work — it is a task you happen to be unable to do at this moment. Writing "do
  not start until X" freezes someone else's work on your own temporary
  limitation.
- **`blocked` already means something else here**: the `dependabot` skill applies
  it to a PR it is deliberately holding open, and `pick-issue` skips those. Don't
  overload it onto issues.

Pick a **title** that's a concise imperative ("Add CSV export to a session's
results", not "Export"). Choose the **labels** that fit (`enhancement`, `bug`,
`documentation`, `good first issue`, …) — they help `pick-issue` later.

## 5. File it

File the issue directly — the interview already gave you sign-off, so don't stop
for a draft review:

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

Write the body to a scratchpad temp file and pass it with `--body-file` (avoids
shell-escaping issues). Add labels the repo actually has (`gh label list`);
create a new label only if the user asks.

## 6. Wire up relationships as real links, not just prose

If the issue is blocked by, blocks, tracks, or otherwise relates to another issue
or PR, **record that as an actual GitHub relationship**, not only a sentence in
the body. Prose ("Blocked by #105, don't start until it lands") is fine as context
and belongs in the issue — but the machine-readable link must exist too, so the
relationship shows on both issues and tooling can see it.

- **Blocked-by / blocking** — use GitHub's issue-dependencies API. `issue_id` is
  the *internal integer id* of the **blocking** issue (not its `#number`), and it
  must be sent as an integer (`-F`, not `-f`, or the API 422s on a string):

  ```bash
  # id of the blocking issue (e.g. #105)
  BLOCKER_ID=$(gh api repos/<owner>/<repo>/issues/105 --jq .id)
  # mark the new issue (e.g. #106) as blocked by it
  gh api --method POST repos/<owner>/<repo>/issues/106/dependencies/blocked_by \
    -F issue_id="$BLOCKER_ID"
  ```

  This creates a reciprocal link: the blocked issue shows **blocked-by**, the
  blocker shows **blocking** (verify with `gh issue view <n>`, whose output
  includes `blocked-by:` / `blocking:` lines).

- **Looser references** (related work, a follow-up, "see also", the issue this
  splits off from) — still use a real cross-reference: mention the other issue/PR
  as `#123` or its full URL in the body so GitHub renders a linked, back-referenced
  mention, rather than describing it in unlinked prose.

Favor the real link every time the relationship is nameable; keep the prose only
as the human-readable *why*.

## Report

Give the user the issue URL and number, its title, and labels. This skill's job
ends at issue creation — don't offer to start implementation or hand the issue to
another skill; picking up work is the user's call (via `pick-issue`/`implement`)
in a separate step. If the discussion revealed the request is really several
issues, say so and offer to file the others too.