write-issue
Use when creating or drafting a GitHub issue, turning a bug, idea, request or audit finding into an issue, or checking whether an existing issue is ready to plan or build from.
reyxdz · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add reyxdz/going-dark --skill write-issue技能说明
name: write-issue description: Use when creating or drafting a GitHub issue, turning a bug, idea, request or audit finding into an issue, or checking whether an existing issue is ready to plan or build from.
Write an issue
What this skill is for
An issue is a specification. Someone who never saw your conversation must be able to plan and build from it without guessing. That means:
- the problem is concrete, with real file names and real numbers;
- every decision says who made it and when;
- what is in scope and what is not is written down;
- "done" can be measured.
You will: collect facts, sort the open points, ask the owner, write the draft from a fixed template, show it, and only then file it on GitHub.
To check an existing issue instead of writing one, do Step 1, then go straight to "Before you send" and answer every question about that issue. Report each "no" with what to add.
How to follow this file
- Do the steps in order, from Step 1 to Step 9. Do not skip a step. Do not change the order.
- Each step has three parts:
- Do — what to do. Commands are shown in code blocks. Replace every
<word in angle brackets>with the real value and remove the brackets. - Check — what must be true before you go on.
- If not — what to do when the check fails.
- Do — what to do. Commands are shown in code blocks. Replace every
- When this file says STOP, stop working, send the message it gives, and wait for the answer. Do not go on until the person answers.
- Never invent a fact. Every file name, line number, number, name and date you write must come from the person, the code, or a command you ran during this task.
- When you cannot check a fact — no access to the repository, a command
fails, the file does not exist — you may still write it if the person told
you, but put
*(unverified: <why>)*right after it. Never write a number or a file path you made up. - The project's own rules win. If a file you read in Step 1 says something
different from this file, do what the project says, and tell the person:
The project's rule "<quote>" replaced this skill's rule "<quote>". - Never create the issue on GitHub until the person has seen the full draft and said yes (Step 8).
- The examples in this file (numbers, copy, file names) only show the shape. Never reuse them as values for a real issue.
Words used in this file
| Word | Meaning |
|---|---|
| owner | The person who decides what is built. Step 1 shows how to find them. |
| owner's handle | The owner's GitHub username, for example reyxdz. |
| bug | Something that worked, or was meant to work, and does not. |
| feature | Something new that people will be able to do. |
| technical issue | A change users do not ask for directly: speed, size, cost, security, cleanup. A complaint like "the list is slow" is a technical issue. |
| owner question | A question whose answer changes what users get, what it costs, or the risk. Step 4 lists them. |
| technical call | A choice about how to build it, which you make yourself and write down. Step 4 lists them. |
| decision record (ADR) | A short document, usually in docs/decisions/ or docs/adr/, recording a choice that is expensive to undo. |
| expensive to undo | Undoing it later would need a data migration, break users or other apps, cost money, or change a public URL or API. |
| sets a precedent | It is the first of its kind in the project, and later work will copy it (the first paged list, the first file upload, the first background job). |
| copy | Any text users will read: buttons, messages, errors, empty pages. |
| scratch folder | A folder outside the repository for temporary files. Use the one your tool gives you (often called a scratchpad or temp folder). If it gives none: /tmp/going-dark on macOS and Linux, %TEMP%\going-dark on Windows. Create it if it is missing. |
| today | Today's date as YYYY-MM-DD, from your environment. If you do not know it, ask. |
Step 1 — Read the project
Do:
- List the project's rule files and read every one that exists:
git ls-files AGENTS.md CLAUDE.md GEMINI.md CONTRIBUTING.md .github/copilot-instructions.md "docs/explanation/*" "docs/guides/*" - Read the issue templates, if any:
git ls-files ".github/ISSUE_TEMPLATE/*" - Read the three most recent issues, to copy their style:
gh issue list --state all --limit 3 --json number,title,labels,body - List the labels that exist:
gh label list - List the decision records:
git ls-files "docs/decisions/*" "docs/adr/*" - Find the owner. In the rule files, look for "owner", "maintainer",
"only … merges". Also read
.github/CODEOWNERSif it exists. If you find a GitHub handle, that is the owner's handle. If not, the owner is the person asking you; you will ask for their handle in Step 5.
Check: you know the owner (or will ask), the labels, and the style of recent issues.
If not: for each thing you could not read, note it. Anything you later
write that depends on it gets *(unverified: …)*.
Step 2 — Decide what kind of issue it is
Do: pick exactly one, using the words table: bug, feature or technical issue.
Check: you picked one, using the first rule that matches:
- It was meant to work and does not ("broken", "never arrives", "error", "stopped working") → bug.
- It works, but too slowly, too big, too costly, or needs cleaning up → technical issue.
- People will be able to do something they cannot do now → feature.
Step 3 — Collect the facts
Do:
- Where in the code. Find the exact file and line:
Writegit grep -n "<function, route or text the person mentioned>"file:linefrom the output, for examplebackend/src/routes/offers.ts:42. If you cannot search the code, use what the person said, exactly as they said it ("near lin