Scope Issue

---
name: scope-issue
description: >
  Writes issue descriptions: a problem paragraph opening with the defect, then a proposal. Use
  when writing or editing an issue (`gh issue create`, `gh api …/issues`, `glab issue create`,
  `-f description=`). Commit messages: use `scope-commit`; MR/PR descriptions: use `scope-mr`.
---

Issue is actionable items, not prose. Read days or weeks later with zero conversation context.

## issue-style

Reader starts the task from the description alone — no chat history. Comments carry the issue's
history; a run that resumes the work reads them too.

### Goal

- Every issue answers: what do I do next.
- Every issue answers: how do I know it's done.

### Shape

- Two parts, in order: problem, proposal.
- Problem opens the description unlabeled. No `## Problem` heading.
- Problem opens with the defect or gap, bolded.
- Background the defect or gap needs follows it.
- Several defects, effects or sites → a `-` list after the opening sentence.
- Evidence (a table, a fenced block) sits under the claim it backs.
- Origin is one clause ("Found by a docs review").
- Each fact appears once.
- Proposal: the next step, under `## Proposal`. Always present.
- Proposal is concrete: a list of actions, a person to engage, or a research issue's questions.
- Proposal ends with a `Done when …` paragraph after its items, naming an observable check. Never a bullet.
- Never end at the problem.
- Meta issue: a paragraph on the work it tracks, then the checklist. No bolded defect, no `## Proposal`.

### Open questions

- User asked for the issue in chat → ask its open questions, milestone included, with
  AskUserQuestion before writing it; write the answers into the issue.
- Issue found during other work (dream-fixer, a review, a lab check) → do not prompt; list the
  open questions as open items in the proposal, or file a `Research:` issue.

### Research

- Proposal would need a guess or an assumption → research issue, not a guessed proposal.
- Title starts `Research:`.
- Proposal lists the questions to answer.
- Deliverable: a findings comment on the issue plus one follow-up issue per gap found. No code.
- User asks for a file → a note in the repo's research docs; the comment carries the rest.
- Done when every question has an answer or its own issue.

### Evidence

- Milestone exit gate is field evidence → one evidence issue in that milestone.
- Title starts `Evidence:`.
- Proposal lists what to deploy and where, the start date, the measurement, and how to collect it.
- Closes with the milestone.

### Meta

- Work spans milestones, or waits on features not built yet → one meta issue tracking it.
- Title starts `Meta:`.
- The checklist follows the opening paragraph, under no heading; one line per piece of work.
- A line is a child issue link, or plain text naming the feature it waits on.
- File a child issue only when its work can start; tick its box when it closes.
- No milestone; each child carries its own.
- Closes when every line is ticked or ruled out.

### Blockers

- Work cannot start until another issue closes → a `Blocked by #<n>` line, one per blocker.
- Blocker lines end the description.
- Filed into a milestone whose description's `Depends on:` has an open milestone → the host's waiting label (`workflow::future` on GitLab).

### Title

- Under 80 chars.
- Name the thing, not the history.
- ❌ "Refactoring the plugins structure to take into account changes in the Express.js library".
- ✅ "Plugins structure refactoring".

### Items

- Multi-part work → `-` bullet list.
- Each item independently completable and verifiable.
- Default: plain `-` bullets.
- `- [ ]` boxes only for complex multi-stage work, or a meta issue's checklist.
- A paragraph contains an action → pull the action into an item; the paragraph keeps only the why.
- Terse only after the next action is stated. "Stand up the lab" is a title, not a description.

### Skimming

- Problem holds only what's needed to act. The reader already works on the project.
- Cite a brief or doc the target forge's readers can open by URL or path, at the claim it backs;
  don't repeat it.
- Problem carries the substance. Longest part.
- Proposal is the outro.

### Format

- Bold the claim a skimmer must land on, not a keyword.
- One bolded phrase per paragraph at most.
- Inline code for identifiers only: file, path, command, config key, label, version, symbol.
- No inline code for emphasis or ordinary nouns.
- Two or more commands or snippets → one fenced block, a `#` comment per case; never inline code in bullets.
- One line per paragraph or list item; never hard-wrap.

### Diagram

- Defect or new design is a relationship between 3 or more named modules or paths → one fenced
  `mermaid` diagram showing it.
- The diagram replaces the prose it depicts.
- At most 8 nodes.
- No styling.
- Each node names a real file, symbol or output.
- Never on a `Research:`, `Evidence:` or `Meta:` issue.
- Syntax: `graph TD`, `id["label"]`, `-->`, `-.->` and `subgraph` only; never `flowchart`,
  `%%{` or `@{`.
- Node id is a short alphanumeric word, never `end`.
- Unsure whether to draw, user asked for the issue in chat → ask the user.

### Names

- Describe behaviour in plain words; a backticked code name is the exception.
- User-facing name (flag, config key, metric, exit code, error string) → no limit.
- Code name (function, type, field — own code or library) → at most three backticked
  occurrences in the whole text.
- Detail that locates a site or names a customer or person outside the project (city, address,
  coordinates, company, contact) → leave it out unless the work depends on it.
- Issue, MR, repo, link or path the target forge's readers cannot open (chat thread, shared doc,
  local file, internal host) → describe it in plain words, or drop it.

### Updates

- An open issue's comments hold every result a later run needs: findings, decisions, progress.
- Repo docs hold only facts that outlive the issue.
- Small amendment that leaves the work remaining unchanged → a new comment; leave the
  description as written.
- Finding with no decision on direction yet → a new comment; leave the description as written.
- Direction decided, title and problem paragraph still hold → rewrite the proposal and its `Done
  when` paragraph, then comment why it changed with the replaced proposal quoted.
- Direction decided, title or problem paragraph no longer holds → file a new issue that links the
  findings comment, then close this one with a `Superseded by #<n>` comment.
- Description is the current spec. Comments are the log.

### Length

- ~250 words the shape. 500 hard cap.
- Fenced blocks are evidence or a diagram, not prose; they don't count toward the cap.
- Background overgrows first. Cut it first.