issue:refine git:20261030.2367b24A

Immutable. This exact content never changes and is served at /api/v1/blob/82f72ff340ee7b0d.

---
name: issue:refine
description: Refining issues with technical context and structured details. Use when asked to refine, draft, or write up an issue, including expanding a brief bug, feature, refactor, or spike (timeboxed investigation) description into a detailed issue suitable for developers and AI agents.
argument-hint: "[--type bug|feature|refactor|spike] [--compact]"
---

# Issue Refinement

## Arguments

Parse `$ARGUMENTS`:

- `--type bug|feature|refactor|spike`: use that type's guide. Default: infer the type per [Issue Types](#issue-types).
- `--compact`: write the trivial body per [Section Selection](#section-selection), still with frontmatter. Default: size the body to the issue.

## Issue Types

| Type | When to Use | Guide |
|------|-------------|-------|
| Bug | Something is broken | `bug.md` |
| Feature | New capability | `feature.md` |
| Refactor | Internal improvement, no behavior change | `refactor.md` |
| Spike | Timeboxed investigation; output is a recommendation, not a shipped change | `spike.md` |

## Workflow

Read the type guide, gather context from code and related issues, and draft the refinement. Write it to `tmp/issue-<slug>.md` and output it for approval. After approval, hand the file to the platform skill (for Linear, `linear:linear`), which owns all save mechanics, including mapping frontmatter to tracker fields. On GitHub, a screenshot the body references by local path goes on `gh issue create --attach`, per `github:attach`.

## Output Structure

YAML frontmatter for the metadata a tracker stores as fields, then the body below the closing `---`. The body leads with the summary prose directly, under no heading.

```markdown
---
title: fix connection pool exhaustion under load   # sentence case, one line, no long parentheticals
type: bug                                           # bug | feature | refactor | spike
labels: [performance, database]                     # optional; neutral tags
priority: high                                      # optional; urgent | high | medium | low
relations:                                          # optional; tracker links per relation
  blocks: []
  blocked-by: []
  related:
    - https://linear.app/acme/issue/ENG-1970
  duplicate-of: []
---

The nightly export marks its run successful even when per-object retrievals
time out, so downstream jobs read a partial snapshot as if it were complete.

[Type-specific sections from guide (select, don't fill)]

## 🤖 Agent Context
```

Populate only the keys you can infer, and drop empty relation lists. The platform skill fills routing and workspace fields (team, assignee, state, estimate) at save time.

A related issue you found belongs under `relations` as a tracker link, kept out of the body. Mention another issue in the body only when it tells the reader something the relation can't: what a prior attempt tried, why upstream work matters. The body has no Related Issues section. Put links the tracker has no field for (cross-tracker issues, upstream bug reports) under [Agent Context](#agent-context).

## Section Selection

Keep a section only when it tells the reader something they couldn't have guessed. Cut sections whose content is tautological ("tests must pass"), template residue ("no behavior change"), or obvious given the issue's size.

For a substantial issue, the opening summary plus one type section is the floor. Grow only when content demands. A trivial issue needs none of that frame: a sentence or two that names the problem and points at the code is enough.

## Agent Context

What you learned exploring the codebase, so the implementing agent doesn't explore it again. Last in the body, under a `## 🤖 Agent Context` heading, which the platform skill turns into a collapsible. Where no platform skill covers the tracker, wrap it in GFM `<details>` at save time.

Write lists of paths, symbols, and commands for an agent. [Style](#style) does not apply: line numbers, ranges, and bare enumeration are fine when they save a search.

Emit only what exploration produced. Drop subsections you can't fill, and the whole section when you explored nothing.

Open the block with one line, `Gathered at <commit> on <date>.` (`git rev-parse --short HEAD`), or `Gathered on <date>.` without a commit, and go straight to the first subsection. The implementer checks every pointer against their own checkout. That check already covers where a finding came from and what you couldn't confirm. State each finding as fact about the code. Pair every line number with its symbol, which survives drift.

```markdown
## 🤖 Agent Context

Gathered at `a1b2c3d` on 1970-01-01.

### Related Code

- `acquire` at `src/pool.ts:88` blocks on an exhausted pool with no deadline
- `release` at `src/pool.ts:140` early-returns on a closed connection, leaking the slot

### Prior Art

- `f0e9d8c` added the same deadline to the write pool. Mirror its test setup.
```

Subsections, in order:

| Section | Content |
|---------|---------|
| Related Code | Files to change or read, with the symbol and why it matters |
| Prior Art | Commits, PRs, or issues that solved a similar problem, and what to take |
| Verification | Test file to extend, suite to run, gate covering this area |
| Search Hints | Search patterns and entry points that found the code |

## Style

Human-facing body only. [Agent Context](#agent-context) has its own rules.

State facts without hedging.

Section headings are title-case noun phrases. Keep them free of sentences, slogans, and "X, not Y" antithesis. Write "Connection Lifecycle" rather than "Pin, don't invalidate".

Use plain words over jargon and marketing. Drop terms like "spike" (as a verb), "seam", "disposition", "reality". Say what the thing does.

Reference code by symbol. Name the function or type and quote the few relevant lines inline. Skip bare line ranges (`file.py:26-56`, `#L26-L56`): they go stale as the file changes. Use a SHA-pinned permalink only when a stable anchor is needed.

Reference issues and PRs as tracker links that expand inline, rather than bare numbers (`ENG-1970`, `!578`, `#123`) a reader can't resolve. The platform skill owns the link syntax.