/raise-issue

name: raise-issue
description: '[Adam''s Skills] Turns "this is broken" into a well-formed issue in the team''s tracker, written in the codebase''s own vocabulary. Built for someone who uses the product and does not read code — it asks a few plain-English questions, works out for itself which part of the code they are describing, checks whether the same thing has already been reported, and files it, but only after they say yes. Use when the user says something is broken, looks wrong, isn''t working, is behaving oddly, seems like a bug, or asks whether they should tell someone about a problem they found; when they say "I found a bug", "the X isn''t working", "should someone look at this?"; or when they paste a screenshot of something that looks wrong. Aliased as /report-issue.'
allowed-tools: Read, Glob, Grep, Bash, Write, AskUserQuestion

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](REFERENCE.md), 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:

| State | What it means | What you do | |---|---|---| | **Reachable** | Tracker found, CLI present and authenticated | Normal path. | | **Found but unreachable** | Tracker found, but `gh`/`glab` is missing, logged out, or returns 403 / "issues disabled" | Name the tracker. Say exactly why you can't post. Give the literal fix. Hand back the web-form URL so they can file it themselves in a browser. | | **No tracker** | Nothing found after looking properly | The no-tracker path below. |

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](REFERENCE.md)). 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

T