Raise Issue

Raise an issue

A good bug report is not a good description. It is a description a developer can act on before they have found the code themselves. That translation is the whole job here.

The person running this skill uses the product. They do not read code, and they should not have to. They will say "the dashboard", "the thing that sends the emails", "the export button spins forever". Your job is to take those words, find what they point at in this repository, confirm the match in plain English, and hand a complete brief to whoever picks the issue up — so nobody has to come back and ask this person a technical question.

Why this skill can be triggered by the model

The omission of disable-model-invocation is deliberate, not an oversight.

The people this skill exists for do not know it exists. They will not type /raise-issue; they will say "this looks wrong" and wait. Model invocation is the only mechanism that reaches them.

Being model-invocable is not unusual here — most of this collection is. What is unusual is the blast radius. Every other model-invocable skill in this collection reports, audits, or edits inside the repo; the worst case is a bad local change the user can undo. This one writes outside it, to a tracker the whole team reads, under the user's own name, where a mistake is public and cannot be quietly reverted. /seatbelt carries a comparable weight and answers it the other way, with explicit invocation only.

So the containment is not the frontmatter. It is step 5: nothing is published, commented on, handed to another skill, or written outside this conversation until a human has read the finished text and said yes. Keep that gate where it is, and keep it ahead of publishing. It is the only thing making auto-invocation safe here, and it is a prose instruction rather than a mechanical lock — so treat it as load-bearing, not as a formality.

Quick start

/raise-issue                                  # asks what went wrong
/raise-issue the export button spins forever  # starts from a description
/report-issue                                 # the same skill

A screenshot pasted into the conversation is a valid starting point. Read it, describe back what you see in it, and confirm you have understood before going further.

Ground rules

These outrank convenience at every step.

• Never show raw code, diffs, stack traces, or log dumps to this person. File paths and line numbers are fine as evidence in the issue; they are not an explanation. If you need to describe a piece of code, describe what a person would see it do.
• Never condescend. No "don't worry about the technical details". Explain plainly, at full respect, and assume they will read what you write.
• A missing tracker is a missing team setup, not their failing. Same for a logged-out CLI, a repo with Issues switched off, or a permission they don't have. Say what is missing and who can fix it. Never apologise on their behalf.
• Never imply they wasted anyone's time. When the answer is "this is better raised with the billing team" or "someone already reported this", that is a good outcome and should read like one.
• No dead ends. Every branch finishes with the person holding either a filed issue or the complete text of one plus a clear next step.
• Read-only on the codebase. The only writes are the issue itself, a saved draft, and — if they agree — docs/agents/issue-tracker.md. All after confirmation.

Workflow

1. Find the issue tracker — three states, not two

Work down the ladder in REFERENCE.md §1, stopping at the first hit: docs/agents/issue-tracker.md, then git remote -v plus the matching CLI, then repo evidence (.github/ISSUE_TEMPLATE/, CONTRIBUTING.md, README badges, tracker URLs in docs, configured MCP servers).

The result is one of three states, and conflating the middle one with the last is the single worst bug this skill can have:

Telling a team that lives on GitHub "you don't seem to have an issue tracker" because gh was logged out is a lie told with confidence, at the end of a ten-minute interview. Check authentication before the interview, not at publish time, so the person knows where this is going while they still have the choice.

If you can confidently infer the tracker and there is no docs/agents/issue-tracker.md, offer to write it yourself (template in REFERENCE.md §2). Do not tell them to go and run somebody else's setup command first. This skill bootstraps its own detection.

2. Interview — always, one to four questions

The interview runs on every run, however clear the request looks. The first description is always under-specified, and the questions are the mechanism that makes the issue worth filing.

Use AskUserQuestion, one topic at a time, in plain English, with no tracker or code vocabulary. Frame every question by what they saw and what they expected — never by implementation. Question bank in REFERENCE.md §3.

Hard rules, all of them:

• Floor of one question. Even a perfect-looking report gets one.
• Hard cap of four before you draft. Ask what is load-bearing. Do not interrogate.
• Offer the exit on every question. Each AskUserQuestion carries a "file it as it is" option. One keystroke ends the interview and moves to drafting.
• "I don't know" is a real answer. Offer it, record it, and never ask it again in another form. For reproduction steps it is recorded verbatim in the issue as "Reporter could not reproduce on demand" — which is information a developer wants, not a gap.
• Narrate before you go quiet. Step 3 takes time and silence reads as a crash. Say something like: "Give me a minute — I'm going to search the code for the parts you described, then come back with what I think you mean in plain English."

This is a priority order, not a checklist — six candidates for four slots at most, and most runs should use fewer. Take them in this order and stop as soon as you can draft something a developer could act on:

1. What happened.
2. What they expected instead.
3. Where they were when it happened.
4. Whether it happens again.
5. How much it is hurting them.
6. What they do and do not want said in the issue.

Anything you can infer from what they already said, or from the screenshot, or from the code in step 3, you do not ask. Items 4 to 6 are usually inferable or genuinely optional; item 4 in particular is the one people cannot answer and the one that makes them give up, so never press it twice.

3. Ground it in the codebase — bounded

This is the step no tracker can do for itself, and the reason this skill exists.

Take the nouns the person used and find what they name in this repository. Search the code and any domain docs — CONTEXT.md, CONTEXT-MAP.md, docs/adr/, glossaries, README — for exact and adjacent matches.

Bound the search, and show that it is bounded:

• At most six terms, chosen by how load-bearing they are.
• At most twelve searches in total.
• A soft budget of about a minute. When it runs out, stop and report what you have.
• Print a one-line progress marker as you go: Looking up: "export button" (2/6).

Build a term map — their word, the project's word, and file:line evidence. Format in REFERENCE.md §4.

Never silently adopt a term. Every issue leads with the reporter's own words, quoted verbatim and unedited. The term map sits below that, explicitly labelled as machine inference, with its evidence, and closes with a line saying that if the mapping is wrong, the human description above is what counts. A confidently mis-grounded issue costs a developer a day; a clearly-labelled guess costs nothing.

Where a term has two plausible candidates, ask — describing each by what the person would see, never by its symbol name. Where it has one confident match, take it and show it in the review. Where it has none, say so in the map. An honest blank is better than a stretch.

4. Draft the brief

Assemble everything a downstream skill or a developer would otherwise have to ask for: the problem in the reporter's words, expected versus actual, reproduction (or the honest note that they could not reproduce it), the affected area in codebase vocabulary with file evidence, severity in terms of impact on their work, the scope boundaries they set, and any screenshots.

Template in REFERENCE.md §5.

4b. Should this be an issue at all?

Not everything described is work for a developer. Judge it, and be willing to say so:

• Not a defect — the product does what it was designed to do and they expected otherwise. Explain what it does and why. Offer to file it as a change request if they still disagree.
• Not a code problem — a permission, a data-entry mistake, an account or billing matter, a how-do-I question. Name who to talk to instead.
• Too thin to act on — after the interview there is still nothing anyone could start from. Say that plainly, and say what would make it actionable.

This is advice, never a refusal. It appears inside the step-5 confirmation alongside the drafted issue, so "file it anyway" is one keystroke away. And it is phrased so that being redirected never reads as having wasted anyone's time.

4c. Has this already been reported?

Always runs. Never skipped.

Two people hitting one bug describe it in two unrelated ways — one says "the export button spins forever", the other says "my March invoice never downloaded" — and neither recognises the other's report. A text search over issue titles is therefore the weakest possible check, and it is the one most tools stop at.

Search primarily by the grounded code area. Step 3 resolved their description to real files and symbols; that is a far better duplicate key than their prose, because it normalises two symptom stories onto one module. Run all three, in this order of weight:

1. By code area — open issues naming the same files, symbols, or component. The primary signal.
2. By symptom text — their own words, plus any error text they quoted.
3. By recency — anything opened in the last few weeks touching that area. A fresh regression attracts several reports fast.

Then classify honestly against the table in REFERENCE.md §6, showing each candidate as a link plus a one-line plain-English summary. The three outcomes:

• Same symptom, same area → offer to add their detail as a comment on the existing issue. Their specific record, number, and date are genuinely useful there.
• Different symptom, same area → file a new issue, linked to the existing one, saying plainly that the two touch the same part of the code and may or may not share a root cause. Never force the choice. Never merge silently.
• No credible match → file normally.

The middle case is the one usually got wrong. Whether the root cause is shared is a diagnosis, and diagnosis is the developer's job. Guessing "duplicate" loses a real bug; guessing "unrelated" costs a developer the link that would have solved both. Linking costs nothing and keeps both.

Every outcome is an offer. "File it as a new issue anyway" is available at each one.

If the tracker cannot be searched — no CLI, no auth, state (b) from step 1 — say so in the confirmation, in those words. Never let silence imply the check passed.

5. Confirm — before anything leaves this conversation

This step comes before publishing, and before any handoff. There is no ordering in which it comes second.

Show the finished issue in full, in plain English. Show the step-4b recommendation and the step-4c duplicate finding alongside it. Say which tracker it will go to, and whether it will be a new issue or a comment on an existing one. Then ask a straight yes/no.

Nothing is published, commented on, or saved before that yes. Do not infer consent from enthusiasm, and do not treat "sounds good" earlier in the conversation as an answer to a question you have not yet asked.

If step 4b recommends against filing, that recommendation is shown here too — and "file it anyway" is always one of the answers. This step advises; it never refuses.

6. Publish — delegate or self-contained

Only after an explicit yes at step 5.

• /to-spec or /to-tickets installed, and a tracker configured → hand them the approved text. Include the handoff instruction from REFERENCE.md §7 verbatim: the clarification is done, the wording is already approved by the reporter, publish it as given, and put no further technical questions to this person — they are not the developer and cannot answer a question about seams.

  These are someone else's skills, and nothing here can enforce that instruction. So the approval must already exist before control leaves this skill: step 5 is the gate, and handing off is itself a publish. If the delegated skill comes back asking this person a technical question, answer it from the brief yourself where the brief settles it, and only go back to them for something genuinely new — in plain language, and never about seams or slicing.

• Otherwise → the self-contained path. Write the issue from REFERENCE.md §5's template and publish with gh issue create / glab issue create.

7. Report back

The link or the file path, and one line on what happens next — who sees it, and roughly when they would normally look. If you filed it as a comment on an existing issue, say which one and why.

When publishing is impossible

Tracker unreachable, no tracker at all, or the publish command failed. The deliverable is still the issue — it just travels by hand.

Print the finished issue in full, in the chat, formatted to paste straight into Slack or an email. That is the deliverable. Then give them:

• The tracker's web-form URL, if there is one, so they can file it in a browser themselves.
• Who to send it to — from CODEOWNERS, the recent authors of the grounded files, or the maintainers named in the README. A name beats a URL.
• The one line to pass to a technical teammate: "turn on GitHub Issues for this repo", or gh auth login, or /setup-matt-pocock-skills.

Offer to save a copy to a file as a backup, never as the answer. If you do save it, run git check-ignore -v <path> first and say out loud if the path is ignored: a file in .scratch/ exists on one laptop and nowhere else, and reporting that as success is a dead end wearing a tick.

When there is genuinely no tracker, add a short plain-English explanation of what an issue tracker is, the two or three realistic options for this repo, and the recommendation to ask a technical teammate to set one up. Tone rule applies: missing team setup, not their failing.

Constraints

• Read-only on the codebase. The only writes are the issue, an optional draft file, and docs/agents/issue-tracker.md — each after explicit confirmation.
• No raw code, diffs, or stack traces shown to the reporter, ever.
• The reporter's verbatim words open every issue. Inference is always labelled as inference.
• Every branch ends with a filed issue or the full text of one plus a named next step.

Detection ladder, issue template, question bank, term-map format, duplicate table, handoff text and error paths: REFERENCE.md.