loom-file-issue

Exact captured content · path .claude/skills/loom-file-issue/SKILL.md · sha256 de77f79b2bb2d165… · revision e50ca4a235d7b8329193ca46f28fda2653cfefc0

Download the exact captured file

---
name: loom-file-issue
description: Files or updates a Loom GitHub issue — duplicate check, a reproduction with versions, the matching issue form and label, a redacted body. Use when asked to open, file or report an issue, bug, regression or feature request, or to add findings to one. Not for security reports (SECURITY.md).
argument-hint: "<what is wrong or wanted>"
metadata:
  internal: true
---

# Filing a Loom issue

An issue is worth filing when a maintainer can act on it without asking a question back. Every issue goes through one of the forms in `.github/ISSUE_TEMPLATE/` (blank issues are off).

## 1. Is it already tracked?

```bash
gh issue list --repo ClickHouse/loom --state all --search "<two or three distinctive terms>" -L 20
gh pr list --repo ClickHouse/loom --state all --search "<same terms>" -L 10
```

With the Loom plugin connected, also call its `loom_tracker_duplicate_check` tool with the title, body and any stack frames: it matches by meaning, not phrase. A duplicate gets a comment with your new evidence on the existing issue, not a second issue. A fix already on `main` gets no issue; say which commit fixed it.

## 2. Reproduce it

- Reproduce on the latest release or `main`, on a private server (`loom-dev-setup`), before writing. If you could not reproduce it, say so: in "How this was found" where the form has it, otherwise in "Additional context", or in the main field of a form with neither.
- Shrink to the smallest sequence: the ops or SDK calls with their inputs, the non-default `LOOM_*` settings, whether auth is on, the rows it depends on and the latest applied migration (`SELECT max(filename) FROM loom._migrations`).
- Keep the `error.code` and the `X-Request-Id` of the failing response; `loom-debug` follows that id to the cause.
- A regression names the PR that caused it (`loom_code_bisect_candidates` ranks the merged PRs of a good/bad window when the plugin is connected): `Caused by: <full PR URL>`.

## 3. Pick the form

The label column is a label that exists in the repository; a form's own `labels:` that does not exist is dropped silently.

| Form (`.github/ISSUE_TEMPLATE/`) | Label | For |
| --- | --- | --- |
| `30_bug-report.yaml` | `bug` | an op, SDK call, CLI command, worker, migration or hook does the wrong thing |
| `40_recall-quality.yaml` | `bug` | search, ask or a context pack returned a wrong result, missed a memory, or failed to abstain |
| `50_performance-issue.yaml` | `bug` | slower, or reads more from ClickHouse, than expected |
| `60_upgrade-compatibility.yaml` | `bug` | an upgrade broke a client, a migration, a field or a setting |
| `70_installation-issue.yaml` | `bug` | does not install, build, boot or connect |
| `20_feature-request.yaml` | `enhancement` | a workflow Loom should support, starting from the use case |
| `80_documentation-issue.yaml` | `documentation` | a page is wrong, missing or unclear |
| `10_question.yaml` | `question` | how to do something |

## 4. Write the body

`gh issue create` cannot fill a YAML form, so write the body with one `### <label>` heading per form field, in the form's order, using the labels exactly as the form shows them (read the YAML). Fill every required field; drop optional ones you have nothing for.

- **Title**: the wrong behaviour as a fact, under ~80 characters. "`memory.search` drops pinned rows when `limit` is below the pin count", not "Search bug" or "Issue with pinned memories".
- **Environment**: paste `loom report` (it prints versions and `loom doctor`, never secret values).
- **How this was found**: pick the option that is true. An agent that found the problem and has not had a person reproduce it says so; that tells a maintainer how much to trust the reproduction.
- **Redaction**: remove tokens, keys, JWTs, passwords, customer data, host names, internal paths and namespaces from logs before pasting, then, in a form with a Redaction field (bug, recall quality, performance, upgrade, installation), end the body with its required checkbox: `### Redaction` and `- [x] I removed tokens, keys, passwords and personal or customer data from everything above.`
- Write in the voice of `loom-writing` and run its checker on the body file.

```bash
python3 .claude/skills/loom-writing/scripts/check_prose.py /path/to/issue.md
gh issue create --repo ClickHouse/loom --title "<title>" --label "<label from the table>" --body-file /path/to/issue.md   # without triage rights: drop --label
```

Creating an issue is public: show the title and body to the requester and file only after they agree, unless they asked you to file it outright.

## 5. After filing

- Link it where it belongs: `Closes: <issue URL>` in the PR that fixes it, `Related:` from other issues.
- New evidence goes in a comment on the issue (`gh issue comment <n> --body-file …`), not an edit that rewrites what others have already read.
- Close only issues you opened, and only with the reason: the fixing PR, or why it is not a bug.