writing-issues
Use when opening or rewriting a GitHub issue on Angus's behalf. A task from a plan, a bug someone described in chat, a proposal that needs decisions, a follow-up noticed in passing. Trigger on "open an issue", "file this", "write up a ticket", "seed issues from the plan", "turn this into an issue", or whenever work needs to be handed to a person or agent who was not in the conversation. Pairs with angusp-voice for the sentences; this skill owns the shape of the issue.
- License 许可
- MIT
- 最近更新
- 2026-11-14
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- writing-issues
- license
- MIT
- metadata
- { "author": "anguspiv", "version": "0.1.1" }
- description
- Use when opening or rewriting a GitHub issue on Angus's behalf. A task from a plan, a bug someone described in chat, a proposal that needs decisions, a follow-up noticed in passing. Trigger on "open an issue", "file this", "write up a ticket", "seed issues from the plan", "turn this into an issue", or whenever work needs to be handed to a person or agent who was not in the conversation. Pairs with angusp-voice for the sentences; this skill owns the shape of the issue.
02 资源文件 1
- 参考文档references/types.md6.0 KB
03 SKILL.md 正文
writing-issues
Overview
An issue is the work queue. Whoever picks it up, a person or an agent, was not in the conversation that produced it and must act from the body alone. So the body says who needs this and why before anything else, states one outcome a person can check without reading code, and lists criteria each with the proof that it holds. Everything an implementer could decide for themselves stays out.
REQUIRED BACKGROUND: angusp-voice sets the sentences (ask first, plain, short). This skill sets the shape, and its budgets for an issue body replace the general ones in angusp-voice.
The shape
The title is the issue's title field, not a line of the body. The body opens
with prose. Headings come after the reader knows what this is. When the
project has an issue template or a voice document, that project's heading
names, heading level, and order win, and the opening paragraph still comes
first; when the two disagree, the issue form wins, because forms are what
people fill in. Without a project template, the default level is ##.
<one paragraph, 60 words or fewer: who needs this, what changes for them,
why now. Not what you read, not the request that produced it.>
## Outcome (work only; a proposal has none until decided)
<one sentence a person can check without reading code>
## Acceptance criteria (work only; 2 to 7, a bug usually 2 or 3)
- [ ] <checkable statement> — proof: <the test file it lives in or will be added to, or the command to run; a path or a command written out, never a directory or "those">
## Decisions (only when something is open)
1. <question>? Default: <answer>, because <one reason>.
## Risk
<low|medium|high> — <reason in the reader's words: what breaks for whom>
## Constraints (only what a cold reader would get wrong)
- <one line each>
## Plan section (task from a plan only)
<plan file> — Task N
## Links (only when there is one: spec section, related issue)
Blocked by: #N (its own line, when something must land first)
## Progress (task from a plan only: the plan's steps as checkboxes)
- [ ] Step 1: …
<details><summary>…</summary> everything else: trade-offs, evidence, the suspected cause </details>
<for an issue that asks for a decision: the reader's next action, one line, with the accept-the-defaults shortcut: or "as proposed">
<a trailing marker the project parses, when there is one, stays the very last line>
A part with nothing in it is left out. A part the project's template requires that you cannot fill reads, as prose, "Not stated; a person writes this before Ready." It is never written as a checkbox, because a checkbox counts as a criterion to the scripts that read issues.
Budgets
Words are counted outside <details> blocks, wherever they fall. A limit is
a ceiling, not a target: land under it with room, and at the line, cut.
| part | limit |
|---|---|
| opening paragraph | 60 words |
task from a plan, outside <details> |
250 words |
bug, outside <details> |
200 words |
proposal, outside <details> |
200 words |
| acceptance criteria | 2 to 7, each with a proof; a bug usually 2 or 3 |
| decisions | one question each, each with a default; list every open one |
Titles
The title says what changes or what is wrong, in the reader's words:
"report --until accepts a future date" not "Bug in report". An issue
seeded from a plan task starts with Task N: and keeps the plan's task
title. No labels in the title. The body states the risk level; the risk:*
label is a person's call unless the project's instructions say the agent
applies it.
Rewriting an existing issue
Keep every heading, every checked box, every form field, and every marker the project parses. Change prose only. If you remove a line, say so in a comment on the issue. A human's edits are not yours to overwrite.
What never goes in
The chat that produced it ("the owner said", "I'm filing this because").
A list of what you read. A proposed implementation outside <details>; it
goes under <details> as a hypothesis, labelled as one. A spec or plan
citation in the opening paragraph; a pointer in parentheses may follow the
sentence that uses it, and the file goes under Plan section or Links.
Angle-bracket slots of any kind, including command syntax: write the value
that was run (--since yesterday), not --since <date>.
Quick reference
| issue | read |
|---|---|
| task from a plan, bug from a chat message, proposal with decisions | references/types.md |
Common drift
| drift | fix |
|---|---|
## Summary as the first line |
Prose paragraph first; the summary is the paragraph. |
| Impact or "who cares" at the bottom | It is the first sentence. |
| Options listed, then "my leaning" at the end | Each option is a numbered question with Default: and one reason. The leaning is the default. |
| Tests described in prose ("the fix should add coverage for…") | Each is a checkbox with proof: naming the test. |
| 500 words of steps and trade-offs | Steps go under ## Progress on a task issue; trade-offs under <details>. |
| Opening paragraph citing spec sections and invariants | One sentence of why; the pointer goes in Plan section or Links. |
A one-line <details> opened early so the rest "doesn't count" |
Budgets count every word outside <details>, wherever it sits. |
| The next action written after a trailing marker | The marker stays last; the next action goes above it. |
04 同仓库更多 Skills
typescript-standards
Use when writing, reviewing, or setting up TypeScript or JavaScript in one of Angus's repositories. Any .ts, .tsx, .js or .mjs change, "add a package", "set up tsconfig", "why is eslint complaining", "review this PR", a new function in a pnpm workspace, a Zod schema, a Vitest test. Also use when a project pulls in @angusp/eslint-config, @angusp/tsconfig, @angusp/prettier-config or @angusp/vitest-config, since this skill says how they are wired and what they assume.
angusp-voice
Use when writing anything on Angus's behalf that another person will read. Chat replies and status updates, pull request descriptions, issue bodies, review and proposal comments, READMEs and docs sections, handoffs. Trigger on "write this up", "draft a reply", "post a comment", "in my voice", "what's the status", or whenever the output is text a person will read rather than code. Also use before posting to GitHub from an agent crew.
__NAME__
Use when [specific triggering situations, symptoms, and phrases]. Say when to use it, not what it does.
beta
Use when a second fixture skill is needed.
alpha
Use when testing the catalog with a <first> fixture skill.
other-name
暂无简介