--- 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: "" 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 "" -L 20 gh pr list --repo ClickHouse/loom --state all --search "" -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: `. ## 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 `###