draft-issue

Produce a ready-to-paste issue (title + Markdown body). This skill NEVER files, creates, or comments on an issue anywhere. No gh issue create, no API calls, no browser. Output only — the issue is the user's to file.

Input (any of)

• A bug just found or discussed in the conversation → draft from what was actually observed.
• A failing test / log output → use it as the evidence, not as the text.
• A plain description from the user → tighten it into the house shape.
• Nothing specific → ask what the bug is. Do not invent one.

The repo outranks this file

Before drafting, look for what the project already requires and follow that instead of the defaults below:

• An issue template — .github/ISSUE_TEMPLATE/ (pick the one matching bug vs feature), .github/ISSUE_TEMPLATE.md, or .gitlab/issue_templates/. Fill its sections as written and keep its headings. If it is a YAML issue form, answer its fields in order, using each field's label as a heading, and honour the ones it marks required.
• Written rules — CONTRIBUTING.md, CLAUDE.md, AGENTS.md: title conventions, required labels, a required version or environment block, a reproduction policy.
• What the tracker actually looks like — gh issue list --limit 5 --json title,body. Real practice beats a stale written rule.

Where the repo is silent, use the style below. Where it conflicts, the repo wins. Two rules hold either way: never file anything, and never sign the draft as AI-authored.

Steps

1. Pin down what actually happens. The symptom the user (or a test) can see, not the mechanism. If a test case covers it, note its name — that is the best reproduction.
2. Pin down the expected behaviour. Usually "the other platform / the previous version does X". Name the reference explicitly (e.g. "the other platform does not have this issue").
3. Separate measured from guessed. Anything you did not observe or read in source is a guess. Guesses either stay out of the issue or are marked ("most likely", "probably the same cause"). Never state an unverified cause as fact — the issue gets read by whoever fixes it.
4. Write the draft — the repo's template if it has one, otherwise the house style below. Match scope: one symptom gets a few lines.
5. Check it before handing it over. Read it once as whoever will fix it:
   • The title alone says what is wrong or wanted.
   • The first sentence of ## Problem alone says what happens and where.
   • It follows Formatting below: no broken lines, no dashes, bold only on categories.
   • Every cause stated as fact was observed or read in source. Guesses are marked.
6. Write it to a file and link it (see Output). The file holds the issue and nothing else; remarks — caveats, what could not be verified, related-but-separate bugs — go in chat beside the link.

House style

The default when the repo prescribes nothing.

Register — plain language, short

Write the way you would describe the bug to a teammate at a desk. Short plain sentences.

Leave out, unless the reader genuinely cannot understand the bug without it:

• file paths, class names, method names, constants
• source citations and code excerpts
• the internal mechanism / architecture explanation
• anything about how it was found, how many runs, which tooling

The bug report says what happens and what should happen. The investigation notes live in the conversation, not in the issue. If a mechanism detail really is load-bearing, one plain sentence — not a paragraph and not a code block.

Title

<TAG> <short plain phrase> — what is wrong or wanted, in the reporter's words.

Tag by what the issue is:

• [BUG] — something is broken.
• [FEATURE] — something is missing.
• [PATCH] — a small correction, cleanup or bump.
• no tag at all when none of them fit. An untagged title is fine; a wrong tag is not.

Examples:

• [BUG] Drag does not prevent scrolling
• [BUG] Scroll taking over does not cancel other gestures
• [FEATURE] Reset control on every test case

Pick the tag from the content, not from the wording of the request. If the user asks for "an issue" about something missing, that is [FEATURE], not [BUG]. When it is genuinely ambiguous, leave the tag off rather than guessing. If the repo labels issues instead of tagging titles, follow the repo.

No ticket ids, no component prefixes, no platform tag in the title unless it is the point.

Body — the shape

## Problem

<Short description. What happens (or what is missing), on which platform/version, and that the reference platform is fine. Usually 1-3 sentences.>

* <only when there are several distinct points to make>
* <one line each>

## Reproduction

<How to trigger it. One line if one line does it. Bug issues only — see below.>

## Problem — always first, always short. Plain prose. Include the comparison ("the other platform does not have this issue") because that is what makes it actionable. Say what should happen when it is not obvious from the symptom.

Bullets — only when there is genuinely more than one point. A single symptom is prose, not a one-item list. When the bullets are categories, such as one per affected screen, bold the category, then a hyphen, then the rest. Otherwise no bold.

## Reproduction — for a bug, always. Imperative, minimal, no ceremony:

• Move the scroll on a tap gesture a tiny amount
• Bullets when there are separate things to try.
• When a test case covers it, name the case and how to run it — one line.

The second section on a non-bug — name it for what it actually is, and only write it when it adds something. A feature usually wants the shape it should take; a patch usually needs nothing beyond ## Problem. Do not force ## Reproduction onto an issue with nothing to reproduce.

Any other section — only if the issue is genuinely unclear without it. Default to two sections, and one is fine. Do not add Expected / Actual / Environment / Severity headings; the template is not a form to fill. If the repo's own template asks for those, that is different — fill what it asks for.

Related bugs

When several symptoms share one cause, prefer ONE issue with the symptoms as bullets over several thin issues. When a related bug is genuinely a different layer, do not fold it in — mention it to the user after the block so they can file it separately.

One plain line inside the issue is enough to link them: This is most likely the same cause as <the other symptom>.

Formatting

• Do not break a sentence across lines. Each paragraph and each bullet is one line in the file. GitHub renders every line break in an issue body, so a hard-wrapped draft shows up broken mid-sentence.
• No em dashes or en dashes. Use a plain hyphen, or the comma, colon or full stop the dash was standing in for.

Footer

Never sign the issue as AI-authored. No "Generated with Claude Code", no Co-authored-by: AI trailer, no robot emoji, no AI attribution of any kind. The draft must read as the author's own. End at the last content line.

Output

Default: write the draft to a file git will never pick up, then link it. Do not paste the whole body into chat as well — the file is the deliverable.

1. Make sure the scratch directory exists and is locally excluded (safe to repeat):

mkdir -p session-materials && grep -qxF 'session-materials/' .git/info/exclude || echo 'session-materials/' >> .git/info/exclude

.git/info/exclude is local to the clone and is never committed, so drafts stay out of git status, out of every diff, and out of every commit. Never add them to .gitignore instead — that file is committed.

2. Write the draft to session-materials/issue-<title-slug>.md. If that path already exists, suffix it -2, -3 rather than overwriting an earlier draft.
3. Report the repo-relative path so it renders as a clickable link, with the title on one line next to it. Your own remarks go in chat beside the link, never inside the file.

When a manager is running you — manage-work or any other orchestrator — write to the path it gave you (fall back to the default above if it gave none) and report that path upstream to the manager, not to the user. The manager owns what the user sees; do not address the user directly in that mode.

No git repo, or the caller named a path → use the caller's path, otherwise a temp directory from mktemp -d. Say where it landed either way.

The file's content is exactly this, and nothing else:

```markdown
[BUG] …

## Problem

…

## Reproduction

…
```

Do not run gh issue create or any other filing command. Filing it is the user's to do.

Worked example

The house style, at the size most bugs deserve:

[BUG] Small scroll detected as a tap

## Problem

When scrolling a list by a small amount it sometimes detects as a tap on iOS. Android does not have this issue. Once scroll is moved it takes over and nothing else is detected.

## Reproduction

Move the scroll on a tap gesture a tiny amount